/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 619a82b485fbf02276ecb8b1cc629f0c8bcda4ca:


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 38 20 32 30 30 38 2f 31  n,v 1.418 2008/1
05f0: 32 2f 31 30 20 31 31 3a 34 34 3a 33 30 20 64 72  2/10 11:44:30 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f  RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
82e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
82f0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
8300: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
8310: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
8320: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
8330: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
8340: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
8350: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8360: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8370: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8380: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8390: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
83a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
83b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
83c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
83d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
83e0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
83f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8400: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8410: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8420: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8430: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8440: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8450: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8460: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8470: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8480: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
8490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
84a0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
84b0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
84c0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
84d0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
84e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
84f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8500: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8510: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8520: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8530: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8540: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8560: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8570: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8590: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
85a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
85b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
85c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
85d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
85f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8600: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8610: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8620: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8640: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8660: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
8670: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8680: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8690: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
86a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
86c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
86d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
86e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
86f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
8700: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8710: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8720: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
8730: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
8740: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
8750: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8780: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8790: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
87a0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
87b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87c0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
87d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
87e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
87f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8800: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
8810: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8820: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
8830: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
8850: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
8860: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ul>.**.** The f
8870: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
8880: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
8890: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
88a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
88b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
88c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
88d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
88e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
88f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
8900: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
8910: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
8920: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
8930: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
8940: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
8950: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8960: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
8970: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
8980: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
8990: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
89a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
89b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
89c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
89d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
89e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
89f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8a00: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8a10: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8a20: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8a30: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8a40: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8a50: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8a60: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8a70: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8a80: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8a90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8aa0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8ab0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8ac0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8ad0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8ae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8af0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8b00: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b10: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8b20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8b30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8b40: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8b50: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8b60: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8b70: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
8ba0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
8bb0: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
8bc0: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
8bd0: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
8be0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8bf0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8c00: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8c10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8c20: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8c30: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8c40: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8c50: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8c60: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8c70: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8c80: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74  e file..**.** At
8c90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
8ca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
8cb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8cc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
8cd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8ce0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8cf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8d00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8d10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8d20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8d30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8d40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8d50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8d60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8d70: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  in..**.** The fl
8d80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8da0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8db0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8dc0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8dd0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8de0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8df0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8e00: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8e10: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8e20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8e30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8e40: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8e50: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8e60: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8e70: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
8e80: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
8e90: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
8ea0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8eb0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8ec0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8ed0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8ee0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ef0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8f00: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
8f10: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8f20: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8f30: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8f40: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8f50: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
8f60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8f70: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
8f80: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
8f90: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
8fa0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
8fb0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
8fc0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
8fd0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
8fe0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
8ff0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9000: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9010: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9020: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9030: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9040: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9050: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9060: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9070: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9080: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
9090: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
90a0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
90b0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
90c0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
90d0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
90e0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
90f0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9100: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9110: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
9120: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
9130: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
9140: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
9150: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
9160: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
9170: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9180: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9190: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
91a0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
91b0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
91c0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
91d0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
91e0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
91f0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9200: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
9210: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
9220: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
9230: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
9240: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
9250: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
9260: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
9270: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66  e..**.*/.typedef
9280: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9290: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
92a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
92b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
92c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
92d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
92e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
92f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9310: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9330: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9340: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9350: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9360: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9370: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9380: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9390: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
93a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
93b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
93c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
93d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
93e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
93f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9400: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9420: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9430: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9460: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9470: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9480: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9490: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
94a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
94b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
94c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
94d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
94e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
94f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9500: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9510: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9520: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9530: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9540: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9550: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9560: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9570: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9580: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
95a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
95b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
95d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
95e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
95f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9600: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9610: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
9620: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
9630: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
9640: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
9650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
9660: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
9680: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9690: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
96a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
96b0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
96c0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
96d0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
96e0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
96f0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
9700: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
9710: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
9720: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
9730: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9740: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
9750: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
9760: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
9770: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
9780: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
9790: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
97a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
97b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
97c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31  VFS method {H111
97d0: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a  90} <H11140>.**.
97e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
97f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9800: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9810: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9820: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9830: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9840: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9850: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
9860: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9870: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9880: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9890: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
98a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
98b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
98c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
98d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
98e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
98f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9900: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9920: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9930: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9940: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9950: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9970: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9980: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9990: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
99a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
99b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
99c0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
99d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99e0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
99f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9a00: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9a30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9a40: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9a50: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9a60: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9a70: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9a80: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a90: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9aa0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
9ab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
9ac0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
9ad0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
9ae0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
9af0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
9b00: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9b10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9b20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9b30: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9b40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9b50: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9b60: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9b70: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9bb0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9bc0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
9bd0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
9be0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9bf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9c00: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9c10: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9c20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9c30: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9c40: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9c50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c60: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9c70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9c80: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9c90: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9ca0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
9cb0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cd0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
9ce0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
9cf0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
9d00: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9d10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9d20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9d30: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9d40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9d50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9d60: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9d70: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
9d80: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20  .** If for some 
9d90: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
9da0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9db0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
9dc0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
9dd0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
9de0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
9df0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
9e00: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
9e10: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
9e20: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
9e30: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
9e40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
9e50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9e70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9e80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9e90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9eb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9ec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9ed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9ee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9ef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9f00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9f10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9f20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9f30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9f50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9f60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9f70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9f80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9f90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9fa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9fb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9fc0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72  lready.  However
9fd0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
9fe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
9ff0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a000: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
a010: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
a020: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
a030: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
a040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a050: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a060: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a070: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a080: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a090: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a0a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a0b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a0c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a0d0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a0e0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a0f0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a100: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a110: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a130: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a160: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a170: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a180: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a190: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a1a0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a1b0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a1c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a1d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a1e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a1f0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a200: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a210: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a220: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a230: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a240: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a250: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a260: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a270: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a280: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a290: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a2a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a2b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a2c0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a2d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a2f0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a300: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a310: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a320: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a330: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a340: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a350: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a360: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a370: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a380: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a390: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a3a0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a3b0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a3d0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a3f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a400: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a410: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a420: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a430: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a440: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a450: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a460: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a470: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a480: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a490: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a4a0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a4b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a4c0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a4d0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a4e0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a4f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a510: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a530: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a540: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a550: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a560: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a570: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a580: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a590: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a5a0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a5b0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a5c0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a5d0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a5e0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a5f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a600: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a610: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a620: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a630: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a640: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a650: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a660: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a670: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a680: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a690: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a6a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a6c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a6d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a6f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a700: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a710: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a720: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a730: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a740: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a750: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a760: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a770: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a780: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a790: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a7b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a7c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a7d0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c  14100} <S20000><
a7e0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a7f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a810: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a820: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a830: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a840: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a850: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a860: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a870: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a880: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a890: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a8a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a8b0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a8c0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a8d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a8e0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a8f0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a900: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a910: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a920: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a930: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a940: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a970: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a980: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a990: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a9a0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a9b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a9c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a9d0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a9e0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa00: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
aa10: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
aa30: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
aa40: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
aa50: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
aa60: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
aa70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa80: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
aa90: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
aaa0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
aab0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
aac0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
aad0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
aae0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aaf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ab00: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ab10: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ab20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ab40: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ab50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ab60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ab70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ab80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
ab90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aba0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
abb0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
abc0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
abd0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
abe0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
abf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ac00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ac10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ac20: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ac30: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ac40: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ac50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ac60: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ac70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ac80: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ac90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
aca0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
acb0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
acc0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
acd0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
ace0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
acf0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
ad00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ad10: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
ad20: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
ad30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ad40: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63  * {H14103} A suc
ad50: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
ad60: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
ad70: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72  onfig()] shall r
ad80: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
ad90: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a    [SQLITE_OK]..*
ada0: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68  *.** {H14106} Th
adb0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
adc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  g()] interface s
add0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
ade0: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20  ITE_MISUSE].**  
adf0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73          if it is
ae00: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77   invoked in betw
ae10: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  een calls to [sq
ae20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ae30: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
ae40: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75      [sqlite3_shu
ae50: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
ae60: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65  {H14120} A succe
ae70: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ae80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
ae90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
aea0: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20  NGLETHREAD]).** 
aeb0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
aec0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
aed0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
aee0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
aef0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d  ..**.** {H14123}
af00: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
af10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
af20: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
af30: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
af40: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D]).**          
af50: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65  shall set the de
af60: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67  fault [threading
af70: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
af80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
af90: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73  14126} A success
afa0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
afb0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
afc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
afd0: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20  ALIZED]).**     
afe0: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74       shall set t
aff0: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
b000: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
b010: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  erialized..**.**
b020: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63   {H14129} A succ
b030: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
b040: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b050: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b060: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b070: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b080: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b090: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c  initialized [sql
b0a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b0b0: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ds].**          
b0c0: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75  object shall cau
b0d0: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  se all subsequen
b0e0: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f  t mutex operatio
b0f0: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20  ns performed.** 
b100: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69           by SQLi
b110: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75  te to use the mu
b120: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74  tex methods that
b130: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e   were present in
b140: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64   X.**          d
b150: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b160: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b170: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b180: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  132} A successfu
b190: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b1b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
b1c0: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b1d0: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
b200: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a  hods] object .**
b210: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b220: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b230: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
b250: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
b260: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74      with the mut
b270: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
b280: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
b290: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b2a0: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66  4135} A successf
b2b0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b2c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
b2e0: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20  C],M).**        
b2f0: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70    where M is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69  ointer to an ini
b310: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65  tialized [sqlite
b320: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
b330: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
b340: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c  t shall cause al
b350: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d  l subsequent mem
b360: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ory allocation o
b370: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  perations.**    
b380: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20        performed 
b390: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
b3a0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
b3b0: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
b3c0: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  n .**          M
b3d0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
b3e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b3f0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
b400: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73  14138} A success
b410: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b420: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b430: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b440: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20  ALLOC],M).**    
b450: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73        where M is
b460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b470: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b480: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68  thods] object sh
b490: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
b4a0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b4b0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b4c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b4d0: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20  bject with .**  
b4e0: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
b4f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65  ry allocation me
b500: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20  thods currently 
b510: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20  in use by.**    
b520: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a        SQLite..**
b530: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73  .** {H14141} A s
b540: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b550: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b560: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b570: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a  G_MEMSTATUS],1).
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b590: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d  l enable the mem
b5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
b5b0: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e  tatus collection
b5c0: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   logic..**.** {H
b5d0: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73  14144} A success
b5e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b610: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20  TATUS],0).**    
b620: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61        shall disa
b630: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ble the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b650: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b660: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37  c..**.** {H14147
b670: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
b680: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b690: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20  ollection logic 
b6a0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
b6b0: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20       enabled by 
b6c0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
b6d0: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73  H14150} A succes
b6e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b6f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b710: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b720: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b730: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b740: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b750: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b760: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b770: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b780: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b790: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b7a0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b7b0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b7c0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b7d0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b7e0: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b7f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b800: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b810: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
b820: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
b830: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
b840: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ize Z..**.** {H1
b850: 34 31 35 33 7d 20 41 20 73 75 63 63 65 73 73 66  4153} A successf
b860: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b870: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b880: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b890: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  CH],S,Z,N).**   
b8a0: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69         where S i
b8b0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
b8c0: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74   shall disable t
b8d0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
b8e0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61  scratch memory a
b8f0: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
b900: 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75 63 63   {H14156} A succ
b910: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a  essful call to.*
b920: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
b930: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b940: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
b950: 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ACHE],S,Z,N).** 
b960: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b970: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b980: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b990: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b9a0: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b9b0: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b9c0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b9d0: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b9e0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b9f0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
ba00: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
ba10: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
ba20: 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20       [pagecache 
ba30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ba40: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73  ] for as many as
ba50: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73   N simulataneous
ba60: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
ba70: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66  ocations each of
ba80: 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b   size Z..**.** {
ba90: 48 31 34 31 35 39 7d 20 41 20 73 75 63 63 65 73  H14159} A succes
baa0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  sful call to.** 
bab0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
bac0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
bad0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
bae0: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  HE],S,Z,N).**   
baf0: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69         where S i
bb00: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
bb10: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74   shall disable t
bb20: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
bb30: 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79  pagecache memory
bb40: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a   allocator]..**.
bb50: 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75  ** {H14162} A su
bb60: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
bb70: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
bb80: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
bb90: 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a  _HEAP],H,Z,N).**
bba0: 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
bbb0: 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d  Z and N are non-
bbc0: 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72  negative integer
bbd0: 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  s and .**       
bbe0: 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65     H is a pointe
bbf0: 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20  r to an aligned 
bc00: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f  memory buffer no
bc10: 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  t less than.**  
bc20: 20 20 20 20 20 20 20 20 5a 20 62 79 74 65 73 20          Z bytes 
bc30: 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e  in size shall en
bc40: 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73  able the [memsys
bc50: 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  5] memory alloca
bc60: 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
bc70: 61 6e 64 20 63 61 75 73 65 20 69 74 20 74 6f 20  and cause it to 
bc80: 75 73 65 20 62 75 66 66 65 72 20 53 20 61 73 20  use buffer S as 
bc90: 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63  its memory sourc
bca0: 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20  e and to use.** 
bcb0: 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d           a minim
bcc0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
bcd0: 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ze of N..**.** {
bce0: 48 31 34 31 36 35 7d 20 41 20 73 75 63 63 65 73  H14165} A succes
bcf0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
bd00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
bd10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
bd20: 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20  P],H,Z,N).**    
bd30: 20 20 20 20 20 20 77 68 65 72 65 20 48 20 69 73        where H is
bd40: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
bd50: 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68  shall disable th
bd60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d  e.**          [m
bd70: 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61  emsys5] memory a
bd80: 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  llocator..**.** 
bd90: 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63 63 65  {H14168} A succe
bda0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
bdb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
bdc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
bdd0: 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a  OKASIDE],Z,N).**
bde0: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
bdf0: 63 61 75 73 65 20 74 68 65 20 64 65 66 61 75 6c  cause the defaul
be00: 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  t [lookaside mem
be10: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
be20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
be30: 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77           for new
be40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
be50: 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20  ctions] to be N 
be60: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73  slots of Z bytes
be70: 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45   each..*/.SQLITE
be80: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
be90: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
bea0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
beb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
bec0: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
bed0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31  connections  {H1
bee0: 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  4200} <S20000>.*
bef0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
bf00: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
bf10: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
bf20: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
bf30: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
bf40: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
bf50: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
bf60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
bf70: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
bf80: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
bf90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
bfa0: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
bfb0: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
bfc0: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
bfd0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bfe0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
bff0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
c000: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
c010: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c020: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f   interface can o
c030: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65  nly be used imme
c040: 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a  diately after.**
c050: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
c060: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61  nnection is crea
c070: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
c080: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b  e3_open()],.** [
c090: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
c0a0: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
c0b0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a  pen_v2()].  .**.
c0c0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
c0d0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
c0e0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
c0f0: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
c100: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
c110: 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  rb - an integer 
c120: 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61  code that indica
c130: 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65  tes what.** aspe
c140: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
c150: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c160: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
c170: 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  red..** The only
c180: 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73   choice for this
c190: 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54   value is [SQLIT
c1a0: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
c1b0: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65  SIDE]..** New ve
c1c0: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  rbs are likely t
c1d0: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  o be added in fu
c1e0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
c1f0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69   SQLite..** Addi
c200: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
c210: 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76   depend on the v
c220: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  erb..**.** INVAR
c230: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
c240: 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20  4203} A call to 
c250: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c260: 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61  ig(D,V,...)] sha
c270: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
c280: 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  E_OK].**        
c290: 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66    if and only if
c2a0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63   the call is suc
c2b0: 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  cessful..**.** {
c2c0: 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f  H14206} If one o
c2d0: 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20  r more slots of 
c2e0: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  the [lookaside m
c2f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
c300: 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
c310: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c320: 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20  ction] D are in 
c330: 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c  use, then a call
c340: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
c350: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c360: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c370: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c380: 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20  ],...) shall.** 
c390: 20 20 20 20 20 20 20 20 20 66 61 69 6c 20 77 69           fail wi
c3a0: 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55  th an [SQLITE_BU
c3b0: 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  SY] return code.
c3c0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20  .**.** {H14209} 
c3d0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
c3e0: 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  l to .**        
c3f0: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f    [sqlite3_db_co
c400: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  nfig](D,[SQLITE_
c410: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c420: 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65  DE],B,Z,N) where
c430: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69  .**          D i
c440: 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62  s an open [datab
c450: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c460: 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20  and Z and N are 
c470: 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
c480: 20 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e       integers an
c490: 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65  d B is an aligne
c4a0: 64 20 62 75 66 66 65 72 20 61 74 20 6c 65 61 73  d buffer at leas
c4b0: 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73  t Z*N bytes in s
c4c0: 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ize.**          
c4d0: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
c4e0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
c4f0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72  y allocator] for
c500: 20 44 20 74 6f 20 75 73 65 20 62 75 66 66 65 72   D to use buffer
c510: 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   B .**          
c520: 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20  with N slots of 
c530: 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a  Z bytes each..**
c540: 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73  .** {H14212} A s
c550: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
c560: 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  o .**          [
c570: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c580: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43  g](D,[SQLITE_DBC
c590: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
c5a0: 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a  ,B,Z,N) where.**
c5b0: 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20 61            D is a
c5c0: 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  n open [database
c5d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
c5e0: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73   Z and N are pos
c5f0: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
c600: 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42    integers and B
c610: 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
c620: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
c630: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f  .**          [lo
c640: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
c650: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20  llocator] for D 
c660: 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20  to a obtain Z*N 
c670: 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20  byte buffer.**  
c680: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65          from the
c690: 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20   primary memory 
c6a0: 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73  allocator and us
c6b0: 65 20 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a  e that buffer.**
c6c0: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e            with N
c6d0: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73   lookaside slots
c6e0: 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 63 68   of Z bytes each
c6f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d  ..**.** {H14215}
c700: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
c710: 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20  ll to .**       
c720: 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63     [sqlite3_db_c
c730: 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45  onfig](D,[SQLITE
c740: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
c750: 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72  IDE],B,Z,N) wher
c760: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20  e.**          D 
c770: 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61  is an open [data
c780: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c790: 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65   and Z and N are
c7a0: 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20   zero shall.**  
c7b0: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 20          disable 
c7c0: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  the [lookaside m
c7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
c7e0: 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f   for D..**.**.*/
c7f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
c800: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
c810: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
c820: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
c830: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c840: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
c850: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
c860: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e  H10155} <S20120>
c870: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
c880: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c890: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c8a0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
c8b0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
c8c0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
c8d0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
c8e0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
c8f0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
c900: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
c910: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
c920: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
c930: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
c940: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
c950: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c960: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
c970: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
c980: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
c990: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
c9a0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
c9b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c9c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65  MALLOC].  By cre
c9d0: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
c9e0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
c9f0: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
ca00: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
ca10: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20  onfig()] during 
ca20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
ca30: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
ca40: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
ca50: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
ca60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
ca70: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53  bsystem.** for S
ca80: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
ca90: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
caa0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
cab0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
cac0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
cad0: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d  ith a built-in m
cae0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
caf0: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65  that is.** perfe
cb00: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
cb10: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
cb20: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
cb30: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
cb40: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
cb50: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
cb60: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
cb70: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
cb80: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
cb90: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
cba0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
cbb0: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
cbc0: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
cbd0: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
cbe0: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
cbf0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
cc00: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
cc10: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
cc20: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
cc30: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
cc40: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
cc50: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
cc60: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
cc70: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
cc80: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
cc90: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
cca0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
ccb0: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61  Malloc, xFree, a
ccc0: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  nd xRealloc meth
ccd0: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
cce0: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
ccf0: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20  (), free(), and 
cd00: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69  realloc() functi
cd10: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
cd20: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a  ndard library..*
cd30: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
cd40: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
cd50: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
cd60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cd70: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
cd80: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
cd90: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
cda0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
cdb0: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
cdc0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
cdd0: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
cde0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
cdf0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
ce00: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
ce10: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ce20: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
ce30: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
ce40: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
ce50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
ce60: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
ce70: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
ce80: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
ce90: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
cea0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
ceb0: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
cec0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
ced0: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
cee0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
cef0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
cf00: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
cf10: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
cf20: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
cf30: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
cf40: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
cf50: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
cf60: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
cf70: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
cf80: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
cf90: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
cfa0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
cfb0: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
cfc0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
cfd0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
cfe0: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
cff0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d000: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
d010: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
d020: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
d030: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
d040: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
d050: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
d060: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
d070: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
d080: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a  d xShutdown..*/.
d090: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d0a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d0b0: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
d0c0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
d0d0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d0e0: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
d0f0: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
d100: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
d110: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
d120: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
d130: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
d140: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
d150: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
d160: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
d170: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
d180: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
d190: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
d1a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
d1b0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
d1c0: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
d1d0: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
d1e0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
d1f0: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
d200: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
d210: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
d220: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
d230: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
d240: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
d250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
d260: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
d270: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
d280: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
d290: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
d2a0: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
d2b0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
d2c0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
d2d0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
d2e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
d2f0: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
d300: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
d310: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
d320: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
d330: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
d340: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e  H10160} <S20000>
d350: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
d360: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
d370: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
d380: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
d390: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d3a0: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
d3b0: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
d3c0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d3d0: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
d3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
d3f0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
d400: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
d410: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
d420: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
d430: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
d440: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
d450: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d460: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
d470: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
d480: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
d490: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
d4a0: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
d4b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d4c0: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
d4d0: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
d4e0: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
d4f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d500: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
d510: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
d520: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
d530: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
d540: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
d550: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
d560: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
d570: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
d580: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d590: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
d5a0: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
d5b0: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
d5c0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
d5d0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
d5e0: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  on disables.** a
d5f0: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
d600: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
d610: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
d620: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
d630: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
d640: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a   thread.</dd>.**
d650: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d660: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
d670: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
d680: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
d690: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
d6a0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
d6b0: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  n disables.** mu
d6c0: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
d6d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d6e0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d6f0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d700: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
d710: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
d720: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
d730: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
d740: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d750: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
d760: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
d770: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
d780: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
d790: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
d7a0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
d7b0: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
d7c0: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
d7d0: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
d7e0: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
d7f0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
d800: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
d810: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d820: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
d830: 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65  e time.  See the
d840: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d850: 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69  ].** documentati
d860: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
d870: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f  l information.</
d880: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d890: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d8a0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
d8b0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d8c0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d8d0: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
d8e0: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
d8f0: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
d900: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
d910: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
d920: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d930: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d940: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d950: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
d960: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
d970: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
d980: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
d990: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d9a0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
d9b0: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
d9c0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
d9d0: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
d9e0: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
d9f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
da00: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
da10: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
da20: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
da30: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
da40: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
da50: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
da60: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
da70: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
da80: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
da90: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
daa0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
dab0: 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  me..** See the [
dac0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dad0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
dae0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
daf0: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  ormation.</dd>.*
db00: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
db10: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
db30: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
db40: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
db50: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
db60: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
db70: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
db80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
db90: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
dba0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
dbb0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
dbc0: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
dbd0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
dbe0: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
dbf0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
dc00: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
dc10: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
dc20: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
dc30: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
dc40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dc50: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
dc60: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
dc70: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
dc80: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
dc90: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
dca0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
dcb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
dcc0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
dcd0: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
dce0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
dcf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
dd00: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
dd10: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
dd20: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
dd30: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
dd40: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
dd50: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
dd60: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
dd70: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
dd80: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
dd90: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
dda0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
ddb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ddc0: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
ddd0: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
dde0: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
ddf0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
de00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
de10: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
de20: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
de30: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
de40: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
de50: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
de60: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
de70: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
de80: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
de90: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
dea0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
deb0: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
dec0: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20   When disabled, 
ded0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
dee0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
def0: 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f  become .** non-o
df00: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
df10: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
df20: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
df30: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
df40: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
df50: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
df60: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
df70: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
df80: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
df90: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
dfa0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20  ].**   </ul>.** 
dfb0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dfc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
dfd0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
dfe0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
dff0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
e000: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
e010: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
e020: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
e030: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
e040: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
e050: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
e060: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
e070: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e080: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66  ach scratch buff
e090: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
e0a0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65   number of buffe
e0b0: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  rs (N).  The sz.
e0c0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
e0d0: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
e0e0: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
e0f0: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
e100: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
e110: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
e120: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
e130: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
e140: 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68  e internal overh
e150: 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ead..** The firs
e160: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
e170: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
e180: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
e190: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
e1a0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
e1b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
e1c0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   no more than on
e1d0: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
e1e0: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72   at once per thr
e1f0: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f  ead, so.** N sho
e200: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
e210: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
e220: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
e230: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a  eads.  The sz.**
e240: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
e250: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65  d be 6 times the
e260: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
e270: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
e280: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61  ge size..** Scra
e290: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20  tch buffers are 
e2a0: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  used as part of 
e2b0: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  the btree balanc
e2c0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66  e operation.  If
e2d0: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61  .** The btree ba
e2e0: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64  lancer needs add
e2f0: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62  itional memory b
e300: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
e310: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72  ovided by.** scr
e320: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20  atch buffers or 
e330: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75  if no scratch bu
e340: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70  ffer space is sp
e350: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51  ecified, then SQ
e360: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20  Lite.** goes to 
e370: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
e380: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  )] to obtain the
e390: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73   memory it needs
e3a0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
e3b0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
e3c0: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
e3d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
e3e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
e3f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
e400: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
e410: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
e420: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
e430: 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
e440: 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
e450: 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20   implemenation. 
e460: 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
e470: 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  uration should n
e480: 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e  ot be used if an
e490: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
e4a0: 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
e4b0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
e4c0: 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
e4d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e4e0: 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e  IG_PCACHE option
e4f0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
e500: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
e510: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41  o this option: A
e520: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
e530: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
e540: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
e550: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
e560: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
e570: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
e580: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75  e sz argument mu
e590: 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66  st be a power of
e5a0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
e5b0: 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65   and 32768.  The
e5c0: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
e5d0: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
e5e0: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
e5f0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
e600: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
e610: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  y..** SQLite wil
e620: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
e630: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
e640: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e650: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
e660: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
e670: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
e680: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
e690: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20  s to cache.  If 
e6a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
e6b0: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
e6c0: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
e6d0: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
e6e0: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
e6f0: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
e700: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
e710: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
e720: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
e730: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
e740: 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
e750: 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e  ion might use on
e760: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
e770: 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f   N buffers to ho
e780: 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63  ld .** memory ac
e790: 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61  counting informa
e7a0: 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tion. </dd>.**.*
e7b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e7c0: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
e7d0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
e7e0: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
e7f0: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
e800: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
e810: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
e820: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
e830: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e840: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
e850: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
e860: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
e870: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
e880: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
e890: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
e8a0: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e8b0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
e8c0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
e8d0: 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65  emory, the numbe
e8e0: 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
e8f0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
e900: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
e910: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
e920: 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ize.  If.** the 
e930: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
e940: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
e950: 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
e960: 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
e970: 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
e980: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
e990: 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
e9a0: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
e9b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
e9c0: 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
e9d0: 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
e9e0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
e9f0: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68  _MALLOC].  If th
ea00: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
ea10: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
ea20: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
ea30: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
ea40: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
ea50: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
ea60: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
ea70: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
ea80: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
ea90: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
eaa0: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
eab0: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
eac0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
ead0: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
eae0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
eaf0: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
eb00: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
eb10: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
eb20: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
eb30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
eb40: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
eb50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
eb60: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
eb70: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
eb80: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
eb90: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
eba0: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
ebb0: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
ebc0: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
ebd0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
ebe0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
ebf0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
ec00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ec10: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
ec20: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
ec30: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ec40: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ec50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ec60: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
ec70: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
ec80: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
ec90: 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
eca0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
ecb0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
ecc0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
ecd0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
ece0: 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
ecf0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
ed00: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
ed10: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
ed20: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
ed30: 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
ed40: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
ed50: 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
ed60: 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
ed70: 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
ed80: 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
ed90: 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
eda0: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
edb0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
edc0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
edd0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
ede0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
edf0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
ee00: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
ee10: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
ee20: 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61   allcation looka
ee30: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  side optimizatio
ee40: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  n.  The first ar
ee50: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
ee60: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
ee70: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
ee80: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
ee90: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
eea0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
eeb0: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
eec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
eed0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
eee0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
eef0: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
ef00: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
ef10: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ef20: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ef30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
ef40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
ef50: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
ef60: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
ef70: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
ef80: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
ef90: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
efa0: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
efb0: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65  on.  SQLite make
efc0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
efd0: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
efe0: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
eff0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
f000: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
f010: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f020: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c  ONFIG_GETPCACHE<
f030: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
f040: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f050: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f060: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f070: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
f080: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f090: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
f0a0: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
f0b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
f0c0: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
f0d0: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
f0e0: 74 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  t object.</dd>.*
f0f0: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#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 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
f120: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* 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 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f150: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
f160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f170: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f180: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
f190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1a0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
f1b0: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
f1c0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f1d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f1e0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f1f0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
f200: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f210: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f220: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f230: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
f240: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f250: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f260: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f270: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
f280: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f290: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f2a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
f2b0: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
f2c0: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
f2d0: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
f2e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f2f0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
f300: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
f310: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
f320: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
f330: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
f340: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f350: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f360: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
f370: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
f380: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
f390: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
f3a0: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
f3b0: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
f3c0: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
f3d0: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
f3e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f3f0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f400: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
f410: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
f420: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f430: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
f440: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
f450: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
f460: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f470: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
f480: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
f490: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a  he_methods* */..
f4a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f4b0: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
f4c0: 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c  tions {H10170} <
f4d0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
f4e0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
f4f0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
f500: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
f510: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
f520: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
f530: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
f540: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
f550: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
f560: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
f570: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
f580: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
f590: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f5a0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
f5b0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
f5c0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
f5d0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
f5e0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
f5f0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
f600: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
f610: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
f620: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
f630: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
f640: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
f650: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
f660: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
f670: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
f680: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
f690: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
f6a0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
f6b0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
f6c0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
f6d0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
f6e0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
f6f0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
f700: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
f710: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
f720: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
f730: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DE</dt>.** <dd>T
f740: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f750: 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
f760: 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
f770: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
f780: 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
f790: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
f7a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
f7b0: 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
f7c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
f7d0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
f7e0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
f7f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
f800: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
f810: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
f820: 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
f830: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
f840: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
f850: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
f860: 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e  rgument may be N
f870: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
f880: 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
f890: 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61  locate the looka
f8a0: 73 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69  side.** buffer i
f8b0: 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
f8c0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
f8d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
f8e0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
f8f0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
f900: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
f910: 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  t and the third 
f920: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
f930: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
f940: 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
f950: 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
f960: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f970: 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
f980: 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
f990: 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
f9a0: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
f9b0: 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
f9c0: 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  nts.</dd>.**.** 
f9d0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
f9e0: 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
f9f0: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
fa00: 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
fa10: 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
fa20: 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
fa30: 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
fa40: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
fa50: 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37  s {H12200} <S107
fa60: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
fa70: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fa80: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
fa90: 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
faa0: 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
fab0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
fac0: 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
fad0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20   of SQLite. The 
fae0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
faf0: 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
fb00: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
fb10: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
fb20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f  compatibility co
fb30: 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  nsiderations..**
fb40: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
fb50: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45  **.** {H12201} E
fb60: 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73  ach new [databas
fb70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68  e connection] sh
fb80: 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20  all have the.** 
fb90: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64           [extend
fba0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
fbb0: 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c 65   feature disable
fbc0: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
fbd0: 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65  .** {H12202} The
fbe0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
fbf0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
fc00: 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20  D,F)] interface 
fc10: 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20  shall enable.** 
fc20: 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64           [extend
fc30: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
fc40: 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62   for the  [datab
fc50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fc60: 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  D.**          if
fc70: 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72   the F parameter
fc80: 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73   is true, or dis
fc90: 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69  able them if F i
fca0: 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20  s false..*/.int 
fcb0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fcc0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
fcd0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
fce0: 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
fcf0: 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
fd00: 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20   Rowid {H12220} 
fd10: 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45  <S10700>.**.** E
fd20: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
fd30: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
fd40: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
fd50: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
fd60: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
fd70: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72  e "rowid". The r
fd80: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
fd90: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
fda0: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
fdb0: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
fdc0: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
fdd0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
fde0: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
fdf0: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
fe00: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
fe10: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
fe20: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
fe30: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
fe40: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
fe50: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
fe60: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
fe70: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
fe80: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
fe90: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
fea0: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
feb0: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
fec0: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
fed0: 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
fee0: 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
fef0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
ff00: 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
ff10: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
ff20: 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65  nt.  If no succe
ff30: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
ff40: 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
ff50: 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
ff60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ff70: 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
ff80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ned..**.** If an
ff90: 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
ffa0: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
ffb0: 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69  r, then the rowi
ffc0: 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  d of the inserte
ffd0: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
ffe0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
fff0: 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
10000 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
10010 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
10020 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
10030 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
10040 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10050 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
10060 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
10070 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
10080 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
10090 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a  trigger fired..*
100a0 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d  *.** An [INSERT]
100b0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
100c0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
100d0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
100e0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
100f0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
10100 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
10110 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10120 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
10130 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
10140 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
10150 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
10160 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
10170 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
10180 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
10190 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
101a0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
101b0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
101c0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
101d0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
101e0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
101f0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
10200 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10210 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
10220 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
10230 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
10240 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
10250 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
10260 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
10270 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
10280 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
10290 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
102a0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
102b0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
102c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
102d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
102e0 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
102f0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
10300 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
10310 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
10320 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
10330 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
10340 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
10350 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
10360 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
10370 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73   {H12221} The [s
10380 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10390 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
103a0 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
103b0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20  n the rowid.**  
103c0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d          of the m
103d0 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
103e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70  ssful [INSERT] p
103f0 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20  erformed on the 
10400 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
10410 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10420 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69  ction] and withi
10430 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
10440 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20  gher level.**   
10450 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
10460 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
10470 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65  if there have be
10480 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67  en no qualifying
10490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 49 4e  .**          [IN
104a0 53 45 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  SERT] statements
104b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d  ..**.** {H12223}
104c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
104d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
104e0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
104f0 6c 20 72 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20  l return the.** 
10500 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61           same va
10510 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  lue when called 
10520 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72  from the same tr
10530 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a  igger context.**
10540 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69            immedi
10550 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64  ately before and
10560 20 61 66 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41   after a [ROLLBA
10570 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  CK]..**.** ASSUM
10580 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
10590 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61  12232} If a sepa
105a0 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
105b0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
105c0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
105d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
105e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
105f0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
10600 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
10610 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20  owid()].**      
10620 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20      function is 
10630 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
10640 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
10650 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a  t insert rowid,.
10660 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
10670 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
10680 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
10690 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
106a0 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  d()] is.**      
106b0 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c      unpredictabl
106c0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
106d0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
106e0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
106f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74  **          last
10700 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a   insert rowid..*
10710 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
10720 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10730 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
10740 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10750 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
10760 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
10770 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
10780 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
10790 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
107a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
107b0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
107c0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
107d0 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
107e0 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
107f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10800 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
10810 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
10820 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10830 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
10840 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
10850 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
10860 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
10870 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
10880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
10890 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
108a0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
108b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
108c0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
108d0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
108e0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
108f0 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
10900 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
10910 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10920 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
10930 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
10940 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
10950 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
10960 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
10970 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
10980 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
10990 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
109a0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
109b0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
109c0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
109d0 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
109e0 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
109f0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
10a00 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
10a10 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
10a20 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
10a30 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10a40 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10a50 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
10a60 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
10a70 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
10a80 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
10a90 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
10aa0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
10ab0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
10ac0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
10ad0 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
10ae0 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
10af0 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
10b00 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
10b10 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
10b20 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
10b30 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
10b40 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
10b50 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
10b60 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
10b70 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
10b80 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
10b90 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
10ba0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
10bb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10bc0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
10bd0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
10be0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
10bf0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
10c00 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
10c10 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
10c20 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
10c30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10c40 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
10c50 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
10c60 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
10c70 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
10c80 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
10ca0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
10cb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
10cc0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
10cd0 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
10ce0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10cf0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
10d00 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
10d10 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
10d20 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10d30 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
10d40 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
10d50 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
10d60 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10d70 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
10d80 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
10d90 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
10da0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10db0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
10dc0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
10dd0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
10de0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
10df0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
10e00 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
10e10 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
10e20 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
10e30 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
10e40 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
10e50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10e60 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
10e70 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10e80 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
10e90 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
10ea0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
10eb0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
10ec0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
10ed0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
10ee0 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
10ef0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
10f00 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
10f10 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
10f20 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
10f30 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
10f40 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
10f50 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
10f60 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
10f70 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
10f80 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
10f90 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
10fa0 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f  table.  Doing so
10fb0 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
10fc0 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
10fd0 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
10fe0 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
10ff0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
11000 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20  table.  Because 
11010 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
11020 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
11030 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
11040 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
11050 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
11060 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
11070 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
11080 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
11090 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
110a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
110b0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
110c0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
110d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
110e0 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
110f0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
11100 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
11110 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
11120 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
11130 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
11140 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
11150 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
11160 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
11170 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75    Or recompile u
11180 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
11190 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54  ITE_OMIT_TRUNCAT
111a0 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20  E_OPTIMIZATION] 
111b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
111c0 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ion to disable t
111d0 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  he.** optimizati
111e0 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65  on on all querie
111f0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
11200 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
11210 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11220 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
11230 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
11240 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  n the number of.
11250 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  **          row 
11260 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
11270 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
11280 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
11290 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
112a0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
112b0 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
112c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
112d0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
112e0 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d    within the sam
112f0 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67  e or higher trig
11300 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
11310 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
11320 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
11330 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c  ot been any qual
11340 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67  ifying row chang
11350 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  es..**.** {H1224
11360 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66  3} Statements of
11370 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54   the form "DELET
11380 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65  E FROM tablename
11390 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20  " with no.**    
113a0 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75        WHERE clau
113b0 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73  se shall cause s
113c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
113d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
113e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
113f0 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72  )] to return zer
11400 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  o, regardless of
11410 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11420 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
11430 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
11440 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  e table..**.** A
11450 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11460 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20  * {A12252} If a 
11470 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
11480 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
11490 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
114a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
114b0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
114c0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
114d0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
114e0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
114f0 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
11500 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61     is unpredicta
11510 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
11520 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
11530 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
11540 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11550 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
11560 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
11570 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
11580 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
11590 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
115a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
115b0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
115c0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
115d0 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
115e0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
115f0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
11600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11610 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
11620 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
11630 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
11640 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
11650 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
11660 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
11670 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
11680 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
11690 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
116a0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
116b0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
116c0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
116d0 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
116e0 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
116f0 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
11700 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
11710 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
11720 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
11730 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
11740 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
11750 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
11760 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
11770 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
11780 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
11790 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
117a0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
117b0 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
117c0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
117d0 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
117e0 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
117f0 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
11800 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
11810 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
11820 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
11830 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
11840 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
11850 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
11860 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
11870 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
11880 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
11890 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
118a0 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
118b0 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
118c0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
118d0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
118e0 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
118f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11900 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
11910 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
11920 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
11930 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
11940 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
11950 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
11960 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
11970 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
11980 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
11990 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
119a0 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
119b0 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
119c0 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
119d0 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72  1" instead.   Or
119e0 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67   recompile using
119f0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11a00 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
11a10 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
11a20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11a30 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a  to disable the.*
11a40 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f  * optimization o
11a50 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a  n all queries..*
11a60 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
11a70 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11a80 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
11a90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11aa0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
11ab0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
11ac0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11ad0 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
11ae0 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
11af0 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
11b00 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11b10 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
11b20 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
11b30 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
11b40 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
11b50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11b60 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
11b70 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
11b80 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
11b90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
11ba0 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
11bb0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
11bc0 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
11bd0 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
11be0 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
11bf0 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
11c00 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
11c10 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
11c20 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
11c30 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
11c40 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
11c50 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11c60 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11c70 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11c80 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
11c90 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11ca0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11cb0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11cc0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11cd0 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
11ce0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11cf0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
11d00 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
11d10 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
11d20 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11d30 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11d40 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11d50 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11d60 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11d80 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
11d90 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
11da0 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
11db0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11dc0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11dd0 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11de0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11df0 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11e00 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11e10 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11e20 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11e30 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11e40 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
11e50 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
11e60 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
11e70 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
11e80 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
11e90 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
11ea0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11eb0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11ec0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11ed0 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
11ee0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
11ef0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
11f00 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
11f10 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
11f20 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
11f30 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
11f40 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
11f50 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
11f60 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11f70 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
11f80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f90 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
11fa0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
11fb0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
11fc0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11fd0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
11fe0 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
11ff0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
12000 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
12010 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
12020 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
12030 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
12040 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
12050 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12060 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
12070 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
12080 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
12090 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
120a0 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
120b0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
120c0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
120d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
120e0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
120f0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
12100 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
12110 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12120 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12130 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12140 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12150 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12160 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
12170 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
12180 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
12190 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
121a0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
121b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
121c0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
121d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
121e0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
121f0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
12200 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
12210 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
12220 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
12230 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
12240 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
12250 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
12260 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
12270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
12280 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
12290 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
122a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
122b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
122c0 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
122d0 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
122e0 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
122f0 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
12300 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
12310 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
12320 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
12330 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
12340 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12350 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
12360 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12370 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
12380 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
12390 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
123a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
123b0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
123c0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
123d0 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
123e0 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
123f0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
12400 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
12410 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
12420 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12430 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
12450 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
12460 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
12470 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
12480 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
12490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
124a0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
124b0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
124c0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
124d0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
124e0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
124f0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
12500 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
12510 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
12520 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
12530 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
12540 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
12550 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
12560 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
12570 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
12580 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
12590 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
125a0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
125b0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
125c0 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
125d0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
125e0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
125f0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
12600 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
12610 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
12620 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
12630 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12640 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
12650 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12660 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
12670 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
12680 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
12690 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
126a0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
126b0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
126c0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
126d0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
126e0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
126f0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
12700 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
12710 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12720 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12730 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
12740 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12750 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12760 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
12770 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
12780 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
12790 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
127a0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
127b0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
127c0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
127d0 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
127e0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
127f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
12800 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12810 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
12820 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12830 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
12840 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
12850 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
12860 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
12870 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
12880 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
12890 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
128a0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
128b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
128c0 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
128d0 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
128e0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
128f0 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
12900 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12910 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
12920 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
12930 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
12940 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
12950 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
12960 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12970 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
12980 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
12990 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
129a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
129b0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
129c0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
129d0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
129e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
129f0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12a00 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12a10 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
12a20 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
12a30 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
12a40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12a50 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
12a60 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
12a70 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
12a80 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
12a90 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
12aa0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
12ab0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
12ac0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
12ad0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12ae0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
12af0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
12b00 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
12b10 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
12b20 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
12b30 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
12b40 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
12b50 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
12b60 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
12b70 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
12b80 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
12b90 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
12ba0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
12bb0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
12bc0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
12bd0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
12be0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
12bf0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
12c00 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
12c10 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
12c20 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12c30 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12c40 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
12c50 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12c60 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12c70 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
12c80 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12c90 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12ca0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12cb0 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
12cc0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12cd0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
12ce0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12cf0 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
12d00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
12d10 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
12d20 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
12d30 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
12d40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12d50 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
12d60 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12d70 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
12d80 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
12d90 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
12da0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
12db0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
12dc0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
12dd0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
12de0 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
12df0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12e00 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12e10 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12e20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12e30 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12e40 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12e50 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12e60 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12e70 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
12e80 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
12e90 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
12ea0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
12eb0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
12ec0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
12ed0 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
12ee0 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
12ef0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
12f00 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
12f10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
12f20 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
12f30 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
12f40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
12f50 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
12f60 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
12f70 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12f80 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12f90 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12fa0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12fb0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
12fc0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
12fd0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
12fe0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
12ff0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13000 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13010 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13020 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13030 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13040 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one 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 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
13070 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
13080 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
13090 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
130a0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
130b0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
130c0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
130d0 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
130e0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
130f0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13100 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13110 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13120 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13130 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13140 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13150 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13160 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
13170 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
13180 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
13190 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
131a0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
131b0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
131c0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
131d0 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
131e0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
131f0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13200 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13210 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13220 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13230 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13240 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13250 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13260 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
13270 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
13280 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
13290 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
132a0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
132b0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
132c0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
132d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
132e0 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
132f0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13300 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13310 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13320 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13330 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13340 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13350 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13360 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
13370 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
13380 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
13390 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
133a0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
133b0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
133c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
133d0 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
133e0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
133f0 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13400 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13410 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13420 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13430 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13440 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13450 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13460 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
13470 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
13480 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
13490 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
134a0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
134b0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
134c0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
134d0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
134e0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
134f0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13500 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13510 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13520 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13530 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13540 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
13550 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13560 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
13570 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
13580 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
13590 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
135a0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
135b0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
135c0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
135d0 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
135e0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
135f0 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13600 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13610 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13620 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13630 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
13640 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13650 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13660 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
13670 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13680 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
13690 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
136a0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
136b0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
136c0 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
136d0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
136e0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
136f0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13700 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13710 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
13720 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
13730 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
13740 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
13750 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
13760 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
13770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13780 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
13790 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
137a0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
137b0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
137c0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
137d0 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49  r..** .** INVARI
137e0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
137f0 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
13800 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
13810 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,C,A)] function 
13820 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a  shall replace.**
13830 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63            busy c
13840 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b  allback in the [
13850 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13860 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65  ion] D with a ne
13870 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  w.**          a 
13880 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
13890 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69   C and applicati
138a0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
138b0 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32  A..**.** {H12312
138c0 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20  } Newly created 
138d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
138e0 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76  tions] shall hav
138f0 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20  e a busy.**     
13900 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20       handler of 
13910 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  NULL..**.** {H12
13920 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72  314} When two or
13930 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20   more [database 
13940 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61  connections] sha
13950 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
13960 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
13970 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
13980 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
13990 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
139a0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
139b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
139c0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
139d0 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
139e0 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68      the cache sh
139f0 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  all be invoked w
13a00 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e  hen the cache en
13a10 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e  counters a lock.
13a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20  .**.** {H12316} 
13a30 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  If a busy handle
13a40 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13a50 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  ns zero, then th
13a60 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
13a70 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
13a80 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
13a90 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73   locking event s
13aa0 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
13ab0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
13ac0 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {H12318} SQLite
13ad0 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74   shall invokes t
13ae0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13af0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13b00 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  ts which.**     
13b10 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
13b20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
13b30 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
13b40 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
13b50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
13b60 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13b70 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
13b80 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13b90 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
13ba0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
13bb0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
13bc0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
13bd0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
13be0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
13bf0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39  S:.**.** {A12319
13c00 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
13c10 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13c20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13c30 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
13c40 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64      or [prepared
13c50 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13c60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13c70 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13c80 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13c90 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13ca0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13cb0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13cd0 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
13ce0 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30  {H12340} <S40410
13cf0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
13d00 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13d10 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13d20 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13d30 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13d40 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13d50 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13d60 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13d70 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
13d80 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13d90 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13da0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13db0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13dc0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13dd0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13de0 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74  ed. {H12343} Aft
13df0 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  er "ms" millisec
13e00 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13e10 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
13e20 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
13e30 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
13e40 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
13e50 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
13e60 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13e70 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
13e80 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
13e90 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
13ea0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
13eb0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
13ec0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
13ed0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
13ee0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
13ef0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f00 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f10 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
13f20 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
13f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13f40 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
13f50 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
13f60 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
13f70 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
13f80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
13f90 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
13fa0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
13fb0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
13fc0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
13fd0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
13fe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
13ff0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
14000 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
14010 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14020 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
14030 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72   override any pr
14040 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
14050 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
14060 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
14070 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14080 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
14090 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
140a0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
140b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
140c0 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68  * {H12343} If th
140d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
140e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
140f0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
14100 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
14110 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
14120 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
14130 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
14140 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f  ll be cleared so
14150 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
14160 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
14170 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
14180 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
14190 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
141a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d  ..**.** {H12344}
141b0 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
141c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
141d0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
141e0 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
141f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
14200 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
14210 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
14220 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65  be set that repe
14230 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
14240 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
14250 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
14260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
14270 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65   | VFS interface
14280 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  ] until.**      
14290 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c      either the l
142a0 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
142b0 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
142c0 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a  ve sleep time.**
142d0 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74            report
142e0 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65  ed back by xSlee
142f0 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
14300 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
14310 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14320 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14330 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14340 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14350 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14360 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14370 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53  ries {H12370} <S
14380 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66  10000>.**.** Def
14390 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
143a0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
143b0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
143c0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
143d0 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
143e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
143f0 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
14400 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
14410 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
14420 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
14430 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
14440 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
14450 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
14460 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
14470 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
14480 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
14490 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
144a0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
144b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
144c0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
144d0 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
144e0 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
144f0 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
14500 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
14510 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
14520 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
14530 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
14540 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
14550 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
14560 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
14570 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
14580 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
14590 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
145a0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
145b0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
145c0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
145d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
145e0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
145f0 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
14600 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
14610 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
14620 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
14630 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
14640 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
14650 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
14660 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
14670 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
14680 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
14690 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
146a0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
146b0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
146c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
146d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
146e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
146f0 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
14700 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
14710 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
14720 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
14730 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
14740 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
14750 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
14760 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14770 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
14780 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
14790 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
147a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
147b0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
147c0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
147d0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
147e0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
147f0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
14800 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
14810 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14820 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
14830 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
14840 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
14850 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14860 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
14870 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
14880 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
14890 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
148a0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
148b0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
148c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
148d0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
148e0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
148f0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
14900 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
14910 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
14920 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
14930 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
14940 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
14950 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
14960 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
14970 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
14980 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
14990 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
149a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
149b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149c0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
149d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
149e0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
149f0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
14a00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
14a10 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
14a20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a30 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
14a40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a50 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
14a60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14a70 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
14a80 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14a90 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
14aa0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
14ab0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
14ac0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
14ad0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14ae0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14af0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14b00 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14b10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14b20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14b30 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14b40 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14b50 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14b60 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14b70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
14b80 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
14b90 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
14ba0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
14bb0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
14bc0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
14bd0 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
14be0 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
14bf0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
14c00 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
14c10 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
14c20 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
14c30 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
14c40 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14c50 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14c60 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14c70 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14c80 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14c90 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14cb0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14cc0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14cd0 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14ce0 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14cf0 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14d00 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14d10 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14d20 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14d30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14d40 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14d50 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14d60 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14d70 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14d80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14d90 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14da0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14db0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14dd0 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14de0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14df0 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14e00 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14e10 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14e20 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14e30 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14e40 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14e50 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14e60 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14e70 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14e80 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14e90 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14ea0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14eb0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14ec0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14ed0 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14ee0 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14ef0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
14f10 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
14f20 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
14f30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14f40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20  .**.** {H12371} 
14f50 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65  If a [sqlite3_ge
14f60 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73  t_table()] fails
14f70 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14f80 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  tion, then.**   
14f90 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20         it shall 
14fa0 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20  free the result 
14fb0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
14fc0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20  truction, abort 
14fd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
14fe0 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73  query in process
14ff0 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65  , skip any subse
15000 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
15010 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
15020 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75     *pazResult ou
15030 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20  tput pointer to 
15040 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20  NULL and return 
15050 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15060 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49  **.** {H12373} I
15070 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70  f the pnColumn p
15080 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
15090 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
150a0 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
150b0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
150c0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
150d0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
150e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
150f0 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
15100 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62    write the numb
15110 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
15120 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15130 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
15140 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
15150 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nColumn..**.** {
15160 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70  H12374} If the p
15170 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nRow parameter t
15180 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
15190 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
151a0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
151b0 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
151c0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
151d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
151e0 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
151f0 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74          writes t
15200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
15210 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
15220 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
15230 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
15240 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20  o *pnRow..**.** 
15250 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65  {H12376} A succe
15260 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
15270 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
15280 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63  _table()] that c
15290 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20  omputes.**      
152a0 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65      N rows of re
152b0 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75  sult with C colu
152c0 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c  mns per row shal
152d0 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c  l make *pazResul
152e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  t.**          po
152f0 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20  int to an array 
15300 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28  of pointers to (
15310 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77  N+1)*C strings w
15320 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a  here the first.*
15330 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72  *          C str
15340 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20  ings are column 
15350 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65  names as obtaine
15360 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  d from.**       
15370 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
15380 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74  mn_name()] and t
15390 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75  he rest are colu
153a0 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73  mn result values
153b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
153c0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
153d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
153e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  )]..**.** {H1237
153f0 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e  9} The values in
15400 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61   the pazResult a
15410 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79  rray returned by
15420 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15430 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15440 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20     shall remain 
15450 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61  valid until clea
15460 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
15470 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
15480 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68  *.** {H12382} Wh
15490 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
154a0 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
154b0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
154c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
154d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75            the fu
154e0 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
154f0 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e   *pazResult to N
15500 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72  ULL, write an er
15510 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
15520 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d          into mem
15530 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
15540 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15550 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20  c()], make.**   
15560 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73         **pzErrms
15570 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20  g point to that 
15580 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61  error message, a
15590 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20  nd return a.**  
155a0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69          appropri
155b0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
155c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
155d0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
155e0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
155f0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
15600 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
15610 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
15620 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
15630 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15640 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15650 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15660 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15670 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15680 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15690 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
156a0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
156b0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
156c0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
156d0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
156e0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
156f0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
15700 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
15710 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
15720 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
15730 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15740 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15750 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15760 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
15770 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
15780 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
15790 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
157a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
157b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
157c0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
157d0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
157e0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
157f0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15800 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15810 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15820 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
15830 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
15840 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
15850 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
15860 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
15870 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
15880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
15890 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
158a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
158b0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
158c0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
158d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
158e0 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
158f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
15900 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
15910 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
15920 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
15930 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
15940 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
15950 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
15960 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
15970 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
15980 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
15990 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
159a0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
159b0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
159c0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
159d0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
159e0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
159f0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
15a00 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15a10 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
15a20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
15a30 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15a40 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
15a50 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
15a60 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
15a70 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
15a80 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
15a90 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
15aa0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
15ab0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
15ac0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15ad0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15ae0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15af0 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
15b00 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15b10 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15b20 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15b30 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
15b40 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
15b50 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
15b60 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
15b70 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
15b80 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
15b90 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
15ba0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15bb0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
15bc0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
15bd0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
15be0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
15bf0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
15c00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
15c10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15c20 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
15c30 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
15c40 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
15c50 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
15c60 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
15c70 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
15c80 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15c90 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
15ca0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
15cb0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15cc0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
15cd0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
15ce0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
15cf0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
15d00 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
15d10 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
15d20 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15d30 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
15d40 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
15d50 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
15d60 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
15d70 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
15d80 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
15d90 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15da0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15db0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15dc0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15dd0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15de0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15df0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15e00 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15e10 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
15e20 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
15e30 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
15e40 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
15e50 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
15e60 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
15e70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
15e80 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15e90 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
15ea0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
15eb0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
15ec0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
15ed0 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
15ee0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
15ef0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
15f00 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
15f10 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
15f20 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
15f30 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
15f40 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15f50 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15f60 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15f70 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15f80 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15f90 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15fa0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15fb0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15fc0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
15fd0 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
15fe0 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
15ff0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16000 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16010 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
16020 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
16030 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
16040 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16050 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
16060 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
16070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
16080 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16090 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
160a0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
160b0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
160c0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
160d0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
160e0 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
160f0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16100 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
16110 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
16120 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
16130 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16140 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
16150 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
16160 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
16170 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
16180 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
16190 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
161a0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
161b0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
161c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
161d0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
161e0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
161f0 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
16200 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
16210 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16220 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
16230 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
16240 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
16250 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
16260 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
16270 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
16280 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
16290 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
162a0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
162b0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
162c0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
162d0 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
162e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
162f0 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
16300 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
16310 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
16320 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
16330 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
16340 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
16350 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
16360 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
16370 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
16380 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
16390 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
163a0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
163b0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
163c0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
163d0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
163e0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
163f0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
16400 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
16410 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
16420 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
16430 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
16440 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
16450 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
16460 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
16470 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
16480 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
16490 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
164a0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
164b0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
164c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
164d0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
164e0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
164f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16500 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
16510 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16520 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16530 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16540 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16550 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16560 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16570 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
16580 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
16590 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
165a0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
165b0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
165c0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
165d0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
165e0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
165f0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
16600 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
16610 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
16620 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
16630 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
16640 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
16650 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
16660 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
16670 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
16680 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
16690 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
166a0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
166b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
166c0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d  :.**.** {H17403}
166d0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
166e0 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
166f0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16700 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
16710 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
16720 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
16730 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
16740 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
16750 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
16760 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
16770 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
16780 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16790 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
167a0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
167b0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
167c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
167d0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ils..**.** {H174
167e0 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
167f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
16800 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
16810 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
16830 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
16840 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
16850 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
16860 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
16870 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
16880 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
16890 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
168a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
168b0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37  o..**.** {H17407
168c0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
168d0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
168e0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
168f0 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
16900 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
16910 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
16920 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16930 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
16940 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
16950 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
16960 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
16970 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
16980 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
16990 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
169a0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
169b0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
169c0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
169d0 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
169e0 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
169f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
16a00 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16a10 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
16a20 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
16a30 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
16a40 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
16a50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
16a60 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
16a70 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
16a80 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
16a90 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
16aa0 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20  system {H17300} 
16ab0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
16ac0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20  he SQLite core  
16ad0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16ae0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
16af0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
16b00 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
16b10 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16b20 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
16b30 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
16b40 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16b50 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
16b60 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
16b70 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
16b80 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
16b90 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
16ba0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
16bb0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16bc0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16bd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
16be0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16bf0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16c00 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16c10 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
16c20 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
16c30 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
16c40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
16c50 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
16c60 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16c70 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16c80 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16c90 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16ca0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16cb0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
16cc0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
16cd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
16ce0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
16cf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
16d00 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
16d10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16d20 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
16d30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
16d40 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
16d50 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
16d60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
16d70 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16d80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
16d90 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
16da0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
16db0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
16dc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
16dd0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16de0 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16df0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16e00 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16e10 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16e20 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16e30 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16e40 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
16e50 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
16e60 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
16e70 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
16e80 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
16e90 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
16ea0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16eb0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16ec0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16ed0 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16ee0 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16ef0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16f00 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16f10 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16f20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16f30 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16f40 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
16f50 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
16f60 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
16f70 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
16f80 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
16f90 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
16fa0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16fb0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  alloc()..**.** T
16fc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
16fd0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
16fe0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
16ff0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
17000 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
17010 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
17020 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
17030 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
17040 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
17050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17060 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
17070 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
17080 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
17090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
170a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
170b0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
170c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
170d0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
170e0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
170f0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17100 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
17110 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
17120 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
17130 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17140 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
17150 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17160 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17170 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
17180 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
17190 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
171a0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
171b0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
171c0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
171d0 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
171e0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
171f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17200 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
17210 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
17220 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
17240 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
17250 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
17260 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
17270 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
17280 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
17290 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
172a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
172b0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
172c0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
172d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
172e0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
172f0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
17300 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
17310 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
17320 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17330 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
17340 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
17350 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
17360 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
17370 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
17380 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17390 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
173a0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
173b0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
173c0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
173d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
173e0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
173f0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
17400 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
17410 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
17420 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
17430 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
17440 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
17450 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
17460 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
17470 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
17480 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
17490 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
174a0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
174b0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
174c0 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
174d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
174e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
174f0 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
17500 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
17510 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
17520 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
17530 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
17540 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
17550 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
17560 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
17570 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
17580 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
17590 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
175a0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
175b0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
175c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
175d0 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
175e0 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
175f0 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
17600 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
17610 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17620 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
17630 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17640 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
17650 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
17660 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
17670 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
17680 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
17690 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
176a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
176b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
176c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
176d0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
176e0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
176f0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
17700 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
17710 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
17720 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
17730 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
17740 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
17750 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
17760 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
17770 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
17780 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
17790 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
177a0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
177b0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
177c0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
177d0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
177e0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
177f0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
17800 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
17810 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
17820 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
17830 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
17840 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
17850 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
17860 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
17870 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
17880 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
17890 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
178a0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
178b0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
178c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
178d0 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71  H17303}  The [sq
178e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
178f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17900 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
17910 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
17920 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63      a newly chec
17930 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
17940 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17950 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
17960 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
17970 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
17980 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
17990 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
179a0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
179b0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20   to fulfill the 
179c0 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b  request..**.** {
179d0 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71  H17304}  The [sq
179e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
179f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17a00 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
17a10 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r if.**         
17a20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e    N is less than
17a30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
17a40 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35  o..**.** {H17305
17a50 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
17a60 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61  free(P)] interfa
17a70 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f  ce releases memo
17a80 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ry previously.**
17a90 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
17aa0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
17ab0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
17ac0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17ad0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
17ae0 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c   making it avail
17af0 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a  able for reuse..
17b00 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20  **.** {H17306}  
17b10 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17b20 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69  e3_free(NULL)] i
17b30 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
17b40 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  op..**.** {H1731
17b50 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
17b60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30  qlite3_realloc(0
17b70 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,N)] is equivale
17b80 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
17b90 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
17ba0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d  ..**.** {H17312}
17bc0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17bd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30  ite3_realloc(P,0
17be0 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17bf0 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17c00 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17c10 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a  te3_free(P)]..**
17c20 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68  .** {H17315}  Th
17c30 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
17c40 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
17c50 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
17c60 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
17c70 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71           and [sq
17c80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f  lite3_free()] fo
17c90 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d  r all of its mem
17ca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
17cb0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nd.**           
17cc0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
17cd0 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  ds..**.** {H1731
17ce0 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  8}  The [sqlite3
17cf0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69  _realloc(P,N)] i
17d00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17d10 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
17d20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
17d30 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65  o a block of che
17d40 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20  cked-out memory 
17d50 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
17d60 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20  tes in size.**  
17d70 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
17d80 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
17d90 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
17da0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32  er..**.** {H1732
17db0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  1}  When [sqlite
17dc0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
17dd0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
17de0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
17df0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
17e00 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72    copies the fir
17e10 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f  st K bytes of co
17e20 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74  ntent from P int
17e30 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20  o the newly.**  
17e40 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
17e50 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20  ed block, where 
17e60 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
17e70 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
17e80 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
17e90 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a    the buffer P..
17ea0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20  **.** {H17322}  
17eb0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
17ec0 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
17ed0 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
17ee0 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
17ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
17f00 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
17f10 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
17f20 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
17f30 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
17f40 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
17f50 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
17f60 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
17f70 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
17f80 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ased..**.** ASSU
17f90 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
17fa0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  A17350}  The poi
17fb0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
17fc0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
17fd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
17fe0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
17ff0 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
18000 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
18010 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
18020 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
18030 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
18040 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
18050 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18060 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
18070 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
18080 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  e.**           n
18090 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
180a0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37  ased..**.** {A17
180b0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63  351}  The applic
180c0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
180d0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
180e0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20   part of.**     
180f0 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
18100 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
18110 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
18120 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
18130 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
18140 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
18150 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
18160 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
18170 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
18180 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
18190 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
181a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
181b0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
181c0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
181d0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
181e0 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
181f0 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
18200 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
18210 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18220 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18230 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
18240 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
18250 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
18260 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
18270 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
18280 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
18290 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
182a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
182b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
182c0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
182d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
182e0 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
182f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18300 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
18310 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18320 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
18330 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
18340 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
18350 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
18360 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
18370 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
18380 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
18390 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
183a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
183b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
183c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
183d0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
183e0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
183f0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
18400 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
18410 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
18420 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
18430 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18440 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18450 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18460 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
18470 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
18480 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
18490 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
184a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
184b0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
184c0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
184d0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
184e0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
184f0 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
18500 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
18510 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
18520 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
18530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
18540 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
18550 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
18560 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
18570 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
18580 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
18590 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
185a0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
185b0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
185c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
185d0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
185e0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
185f0 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
18600 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
18610 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
18620 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
18630 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18640 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
18650 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18660 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
18670 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
18680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
18690 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
186a0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
186b0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
186c0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
186d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
186e0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
186f0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
18700 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
18710 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
18720 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
18730 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32  tor {H17390} <S2
18740 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0000>.**.** SQLi
18750 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
18760 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
18770 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
18780 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
18790 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
187a0 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73  ct random ROWIDs
187b0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
187c0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
187d0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
187e0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
187f0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
18800 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50  le ROWID.  The P
18810 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
18820 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
18830 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
18840 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
18850 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
18860 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
18870 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
18880 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
18890 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
188a0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
188b0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
188c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
188d0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
188e0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
188f0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
18900 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
18910 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
18920 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
18930 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
18940 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
18950 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
18960 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
18970 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
18980 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
18990 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
189a0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
189b0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
189c0 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73  ect..** On all s
189d0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
189e0 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
189f0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
18a00 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
18a10 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
18a20 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
18a30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
18a40 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
18a50 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49   method..**.** I
18a60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
18a70 20 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73   {H17392} The [s
18a80 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18a90 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  s(N,P)] interfac
18aa0 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73  e writes N bytes
18ab0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
18ac0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
18ad0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
18ae0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f  nto buffer P..*/
18af0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
18b00 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
18b10 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
18b20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
18b30 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
18b40 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
18b50 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30  {H12500} <S70100
18b60 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
18b70 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
18b80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b90 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
18ba0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
18bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
18bc0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
18bd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
18be0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
18bf0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
18c00 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
18c10 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
18c20 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
18c30 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
18c40 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
18c50 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
18c60 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
18c70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18c80 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
18c90 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
18ca0 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73  ()].  At various
18cb0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
18cc0 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
18cd0 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
18ce0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
18cf0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
18d00 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
18d10 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
18d20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
18d30 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
18d40 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
18d50 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
18d60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18d70 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
18d80 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
18d90 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
18da0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
18db0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
18dc0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
18dd0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
18de0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
18df0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
18e00 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
18e10 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
18e20 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
18e30 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
18e40 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
18e50 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
18e60 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20  h an error.  If 
18e70 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18e80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18e90 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
18ea0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
18eb0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
18ec0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
18ed0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
18ee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
18ef0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
18f00 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
18f10 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
18f20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
18f30 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
18f40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
18f50 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
18f60 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
18f70 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
18f80 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
18f90 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
18fa0 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74  d is ok.  When t
18fb0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
18fc0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
18fd0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
18fe0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
18ff0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
19000 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
19010 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
19020 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
19030 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
19040 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
19050 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
19060 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68  s denied.  If th
19070 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
19080 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
19090 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
190a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
190b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
190c0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
190d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
190e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
190f0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
19100 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
19110 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
19120 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
19130 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
19140 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
19150 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
19160 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
19170 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
19180 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
19190 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
191a0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
191b0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
191c0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
191d0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
191e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  le..**.** The fi
191f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
19200 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19210 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19220 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
19230 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
19240 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
19250 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
19260 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f  erface. The seco
19270 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
19280 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
19290 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
192a0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
192b0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
192c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
192d0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
192e0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
192f0 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
19300 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
19310 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
19320 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
19330 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
19340 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
19350 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
19360 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
19370 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
19380 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
19390 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
193a0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
193b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
193c0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
193d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
193e0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
193f0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
19400 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
19410 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
19420 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
19430 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
19440 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
19450 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
19460 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
19470 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
19480 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
19490 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
194a0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
194b0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
194c0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
194d0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
194e0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
194f0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
19500 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
19510 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
19520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
19530 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
19540 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
19550 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
19560 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
19570 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
19580 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
19590 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
195a0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
195b0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
195c0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
195d0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
195e0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
195f0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
19600 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
19610 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
19620 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
19630 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
19640 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
19650 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
19660 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
19670 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
19680 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
19690 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
196a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
196b0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
196c0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
196d0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
196e0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
196f0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
19700 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
19710 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
19720 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
19730 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
19740 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
19750 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19760 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
19770 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
19780 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19790 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
197a0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
197b0 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
197c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
197d0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
197e0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
197f0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
19800 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
19810 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
19820 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19830 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
19840 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
19850 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
19860 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19870 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
19880 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
19890 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
198a0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
198b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
198c0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
198d0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
198e0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
198f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
19900 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
19910 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
19920 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
19930 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74  *.** When [sqlit
19940 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19950 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
19960 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
19970 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
19980 74 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65  t might be repre
19990 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
199a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
199b0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
199c0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
199d0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
199e0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
199f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
19a00 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
19a10 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
19a20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
19a30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
19a40 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  p()]..**.** Note
19a50 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
19a60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
19a70 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
19a80 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
19a90 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
19aa0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
19ab0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
19ac0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
19ad0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
19ae0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
19af0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
19b00 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
19b10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31  S:.**.** {H12501
19b20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
19b30 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
19b40 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
19b50 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
19b60 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
19b70 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
19b80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19b90 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
19ba0 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
19bb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
19bc0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
19bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
19be0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
19bf0 67 20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f  g parseed and co
19c00 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mpiled..**.** {H
19c10 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
19c20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19c30 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
19c40 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
19c50 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
19c60 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
19c70 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
19c80 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
19c90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19ca0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65  application inte
19cb0 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20  rface call that 
19cc0 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20  caused.**       
19cd0 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65     the authorize
19ce0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
19cf0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74  n shall fail wit
19d00 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
19d10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
19d20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
19d30 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
19d40 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
19d50 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e  ** {H12504} When
19d60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19d70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19d80 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
19d90 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20  e operation.**  
19da0 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65          describe
19db0 64 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e  d is processed n
19dc0 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ormally..**.** {
19dd0 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65  H12505} When the
19de0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19df0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19e00 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
19e10 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 6c  **          appl
19e20 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63  ication interfac
19e30 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  e call that caus
19e40 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
19e50 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
19e60 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
19e70 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20  all fail.**     
19e80 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51       with an [SQ
19e90 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
19ea0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72  r code and an er
19eb0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
19ec0 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69          explaini
19ed0 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69  ng that access i
19ee0 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  s denied..**.** 
19ef0 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20  {H12506} If the 
19f00 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
19f10 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
19f20 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
19f30 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
19f40 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53   callback) is [S
19f50 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20  QLITE_READ] and 
19f60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19f70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
19f80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19f90 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65  ITE_IGNORE], the
19fa0 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
19fb0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
19fc0 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20  tructed to.**   
19fd0 20 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20         insert a 
19fe0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
19ff0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
1a000 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
1a010 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  ld have.**      
1a020 20 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66      been read if
1a030 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1a040 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a   been returned..
1a050 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49  **.** {H12507} I
1a060 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
1a070 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
1a080 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a090 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
1a0a0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
1a0b0 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68   is anything oth
1a0c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1a0d0 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  READ], then.**  
1a0e0 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
1a0f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f   of [SQLITE_IGNO
1a100 52 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65  RE] has the same
1a110 20 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49   effect as [SQLI
1a120 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DENY]..**.** 
1a130 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72  {H12510} The fir
1a140 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1a150 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a160 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1a170 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
1a180 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1a190 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
1a1a0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a1b0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1a1c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d  ..**.** {H12511}
1a1d0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1a1e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1a1f0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1a200 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
1a210 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
1a220 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
1a230 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
1a240 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
1a250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
1a260 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
1a270 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68  *.** {H12512} Th
1a280 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1a290 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1a2a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1a2b0 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
1a2c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a2d0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
1a2e0 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ntain.**        
1a2f0 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
1a300 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1a310 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1a320 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
1a330 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
1a340 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
1a350 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
1a360 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20  verrides.**     
1a370 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75       any previou
1a380 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75  sly installed au
1a390 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1a3a0 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20  {H12521} A NULL 
1a3b0 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
1a3c0 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
1a3d0 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  zation.**       
1a3e0 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69     callback is i
1a3f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1a400 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75  12522} The defau
1a410 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  lt authorizer is
1a420 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1a430 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a440 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1a450 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1a460 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1a470 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1a480 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1a490 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1a4a0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1a4b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a4c0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1a4d0 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  turn Codes {H125
1a4e0 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  90} <H12500>.**.
1a4f0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1a500 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1a510 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a520 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
1a530 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
1a540 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
1a550 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
1a560 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
1a570 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
1a580 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
1a590 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
1a5a0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
1a5b0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
1a5c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a5d0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1a5e0 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
1a5f0 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
1a600 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1a610 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
1a620 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1a630 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1a640 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1a650 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1a660 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1a670 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1a680 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1a690 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1a6a0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1a6b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1a6c0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1a6d0 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48  odes {H12550} <H
1a6e0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
1a6f0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1a700 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
1a710 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
1a720 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1a730 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
1a740 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
1a750 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
1a760 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
1a770 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
1a780 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1a790 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
1a7a0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
1a7b0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1a7c0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
1a7d0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1a7e0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
1a7f0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
1a800 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
1a810 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a820 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
1a830 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
1a840 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
1a850 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
1a860 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
1a870 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
1a880 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
1a890 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1a8a0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
1a8b0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1a8c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a8d0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1a8e0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1a8f0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1a900 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1a910 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1a920 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a930 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
1a940 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1a950 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a960 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1a970 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1a980 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1a990 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1a9a0 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
1a9b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a9c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a9d0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1a9e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1a9f0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1aa00 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1aa10 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1aa20 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1aa30 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1aa40 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1aa50 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1aa60 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1aa70 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
1aa80 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1aa90 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65  .** {H12551} The
1aaa0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1aab0 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20  r to an.**      
1aac0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
1aad0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1aae0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1aaf0 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69  k] shall be an i
1ab00 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
1ab10 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
1ab20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
1ab30 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1ab40 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a  s what action.**
1ab50 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69            is bei
1ab60 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  ng authorized..*
1ab70 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68  *.** {H12552} Th
1ab80 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
1ab90 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a  rameters to the.
1aba0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1abb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1abc0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74  zer | authorizat
1abd0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a  ion callback].**
1abe0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
1abf0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1ac00 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1ac10 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  on which.**     
1ac20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
1ac30 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
1ac40 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
1ac50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1ac60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
1ac70 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
1ac80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1ac90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1aca0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1acb0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1acc0 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62  allback] shall b
1acd0 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  e the name.**   
1ace0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61         of the da
1acf0 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a  tabase (example:
1ad00 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
1ad10 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1ad20 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  able..**.** {H12
1ad30 35 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72  554} The 6th par
1ad40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1ad50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ad60 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ad70 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1ad80 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62  allback] shall b
1ad90 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  e the name.**   
1ada0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
1adb0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
1adc0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
1add0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1ade0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1adf0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1ae00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
1ae10 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
1ae20 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
1ae30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d  **          top-
1ae40 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1ae50 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1ae60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ae70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1ae80 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1ae90 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1aea0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1aeb0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1aec0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1aed0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1aee0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1aef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1af00 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1af10 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1af20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1af30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1af40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1af50 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1af60 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1af70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1af80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1af90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1afa0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1afb0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1afc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1afd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1afe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aff0 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1b000 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1b010 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b020 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b040 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1b050 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1b060 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b070 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b080 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b090 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1b0a0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1b0b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b0c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b0d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b0e0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1b0f0 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1b100 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b110 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b120 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1b130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1b140 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b150 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b160 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b170 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
1b180 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
1b190 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1b1a0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1b1b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b1c0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
1b1d0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
1b1e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b1f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b200 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b210 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1b220 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
1b230 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b240 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b250 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b260 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1b270 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
1b280 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b290 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b2a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b2b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
1b2c0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
1b2d0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1b2e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b2f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b300 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
1b310 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
1b320 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1b330 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b350 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
1b360 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
1b370 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b3a0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
1b3b0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
1b3c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b3d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b3e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b3f0 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
1b400 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
1b410 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b420 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
1b440 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
1b450 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
1b460 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
1b470 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
1b480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1b490 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
1b4a0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
1b4b0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1b4c0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1b4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
1b4e0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
1b4f0 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
1b500 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
1b510 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b520 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
1b530 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
1b540 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
1b550 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1b560 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b570 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
1b580 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1b590 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
1b5a0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1b5b0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1b5c0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
1b5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b5e0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
1b5f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b600 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b610 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
1b620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
1b630 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1b640 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
1b650 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b660 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
1b670 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
1b680 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1b690 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
1b6a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b6b0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
1b6c0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
1b6d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1b6e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b6f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b700 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
1b710 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
1b720 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b730 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b740 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b750 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
1b760 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
1b770 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b780 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1b790 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b7a0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
1b7b0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
1b7c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b7d0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1b7e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b7f0 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
1b800 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
1b810 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b820 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
1b830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b840 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1b850 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1b860 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1b870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b880 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1b890 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1b8a0 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34  s {H12280} <S604
1b8b0 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  00>.** EXPERIMEN
1b8c0 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TAL.**.** These 
1b8d0 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
1b8e0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
1b8f0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
1b900 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
1b910 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
1b920 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
1b930 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
1b940 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ts..**.** The ca
1b950 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1b960 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1b970 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1b980 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1b990 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1b9a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1b9b0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1b9c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1b9d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ()]..** The call
1b9e0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55  back returns a U
1b9f0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1ba00 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1ba10 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74  ent text.** as t
1ba20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1ba30 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1ba40 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1ba50 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72   callbacks occur
1ba60 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1ba70 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1ba80 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1ba90 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1baa0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1bab0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1bac0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1bad0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1bae0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ger..**.** The c
1baf0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1bb00 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1bb10 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1bb20 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1bb30 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1bb40 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1bb50 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1bb60 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
1bb70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1bb80 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
1bb90 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
1bba0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
1bbb0 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
1bbc0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
1bbd0 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ok to run..**.**
1bbe0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1bbf0 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20  ** {H12281} The 
1bc00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1bc10 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1bc20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1bc30 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ] .**          s
1bc40 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  hall be invoked.
1bc50 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
1bc60 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
1bc70 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1bc80 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
1bc90 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
1bca0 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
1bcb0 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
1bcc0 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
1bcd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20  .**.** {H12282} 
1bce0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
1bcf0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73  lite3_trace()] s
1bd00 68 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68  hall override th
1bd10 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  e previously.** 
1bd20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
1bd30 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61  red trace callba
1bd40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  ck..**.** {H1228
1bd50 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20  3} A NULL trace 
1bd60 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64  callback shall d
1bd70 69 73 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a  isable tracing..
1bd80 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54  **.** {H12284} T
1bd90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1bda0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
1bdb0 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65  allback shall be
1bdc0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
1bdd0 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
1bde0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
1bdf0 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
1be00 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
1be10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
1be20 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
1be30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
1be40 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
1be50 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1be60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1be70 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
1be80 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
1be90 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
1bea0 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
1beb0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
1bec0 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
1bed0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1bee0 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
1bef0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
1bf00 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
1bf10 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
1bf20 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
1bf30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
1bf40 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
1bf50 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ram..**.** {H122
1bf60 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
1bf70 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1bf80 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
1bf90 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
1bfa0 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
1bfb0 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
1bfc0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
1bfd0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38  s..**.** {H12288
1bfe0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
1bff0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
1c000 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
1c010 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
1c020 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
1c030 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c040 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
1c050 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20  .**.** {H12289} 
1c060 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1c070 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1c080 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1c090 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
1c0a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1c0b0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
1c0c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
1c0d0 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
1c0e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
1c0f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
1c100 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
1c110 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
1c120 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
1c130 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
1c140 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
1c150 48 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  H12290} The thir
1c160 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
1c170 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1c180 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
1c190 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
1c1a0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
1c1b0 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
1c1c0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
1c1d0 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
1c1e0 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
1c1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
1c200 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
1c210 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50  h..*/.SQLITE_EXP
1c220 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1c230 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1c240 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1c250 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1c260 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1c270 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1c280 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1c290 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1c2a0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1c2b0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1c2c0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1c2d0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1c2e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c2f0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1c300 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ess Callbacks {H
1c310 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12910} <S60400>.
1c320 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
1c330 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20  ne configures a 
1c340 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c350 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72  n - the.** progr
1c360 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74  ess callback - t
1c370 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70  hat is invoked p
1c380 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1c390 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69  ng long.** runni
1c3a0 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ng calls to [sql
1c3b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1c3c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1c3d0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  nd.** [sqlite3_g
1c3e0 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e  et_table()].  An
1c3f0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1c400 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1c410 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1c420 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1c430 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1c440 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70  ..**.** If the p
1c450 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1c460 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1c470 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1c480 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1c490 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1c4a0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1c4b0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1c4c0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1c4d0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1c4e0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1c4f0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1c500 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1c510 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1c520 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1c530 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1c540 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1c550 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1c560 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1c570 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1c580 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1c590 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1c5a0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1c5b0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1c5c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1c5d0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1c5e0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1c5f0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1c600 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1c610 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20  .**.** {H12911} 
1c620 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1c630 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1c640 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   by sqlite3_prog
1c650 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a  ress_handler().*
1c660 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
1c670 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1c680 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1c690 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1c6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1c6b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1c6c0 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65  .** {H12912} The
1c6d0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1c6e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
1c6f0 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76  ce for every N v
1c700 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20  irtual.**       
1c710 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64     machine opcod
1c720 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1c730 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1c740 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1c750 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
1c760 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c770 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67  )] call that reg
1c780 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
1c790 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
1c7a0 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  .  If N is less 
1c7b0 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f  than 1, sqlite3_
1c7c0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1c7d0 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ().**          a
1c7e0 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c  cts as if a NULL
1c7f0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c800 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 63 69  r had been speci
1c810 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  fied..**.** {H12
1c820 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73  913} The progres
1c830 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c  s callback itsel
1c840 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20  f is identified 
1c850 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  by the third.** 
1c860 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
1c870 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  t to sqlite3_pro
1c880 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e  gress_handler().
1c890 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20  .**.** {H12914} 
1c8a0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
1c8b0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
1c8c0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c8d0 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  ) is a.**       
1c8e0 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20     void pointer 
1c8f0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72  passed to the pr
1c900 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a  ogress callback.
1c910 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
1c920 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69  tion each time i
1c930 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  t is invoked..**
1c940 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20  .** {H12915} If 
1c950 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
1c960 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c  e3_step()] resul
1c970 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e  ts in fewer than
1c980 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20   N opcodes.**   
1c990 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 78 65         being exe
1c9a0 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20  cuted, then the 
1c9b0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1c9c0 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b  k is never invok
1c9d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1c9e0 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f  6} Every call to
1c9f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
1ca00 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a  ss_handler()].**
1ca10 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72            overwr
1ca20 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75  ites any previou
1ca30 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 70  sly registered p
1ca40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1ca50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20  .**.** {H12917} 
1ca60 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1ca70 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
1ca80 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f   is NULL then no
1ca90 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20   progress.**    
1caa0 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73        handler is
1cab0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
1cac0 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68 65 20  {H12918} If the 
1cad0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1cae0 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  k returns a resu
1caf0 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c  lt other than 0,
1cb00 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
1cb10 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69    the behavior i
1cb20 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  s a if [sqlite3_
1cb30 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61 64  interrupt()] had
1cb40 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
1cb50 20 20 20 20 20 20 20 20 20 20 3c 53 33 30 35 30            <S3050
1cb60 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  0>.*/.void sqlit
1cb70 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1cb80 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1cb90 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1cba0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1cbb0 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1cbc0 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1cbd0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
1cbe0 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a  2700} <S40200>.*
1cbf0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1cc00 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1cc10 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1cc20 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
1cc30 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
1cc40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1cc50 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  . The filename a
1cc60 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1cc70 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1cc80 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1cc90 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1cca0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1ccb0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1ccc0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1ccd0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1cce0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64  3_open16(). A [d
1ccf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd00 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
1cd10 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
1cd20 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
1cd30 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
1cd40 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
1cd50 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
1cd60 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
1cd70 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1cd80 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
1cd90 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
1cda0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
1cdb0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
1cdc0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
1cdd0 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
1cde0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1cdf0 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49  e3].** object. I
1ce00 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1ce10 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1ce20 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1ce30 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1ce40 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1ce50 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1ce60 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1ce70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1ce80 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
1ce90 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1cea0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1ceb0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1cec0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1ced0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1cee0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1cef0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1cf00 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  or..**.** The de
1cf10 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1cf20 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1cf30 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1cf40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1cf50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1cf60 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1cf70 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1cf80 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1cf90 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1cfa0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1cfb0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1cfc0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1cfd0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1cfe0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1cff0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1d000 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1d010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d020 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1d030 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1d040 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1d050 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1d060 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1d070 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1d080 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1d090 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1d0a0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1d0b0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1d0c0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1d0d0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1d0e0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1d0f0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1d100 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1d110 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1d120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d130 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70  on.  The flags p
1d140 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b  arameter can tak
1d150 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1d160 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1d170 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1d180 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1d190 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1d1a0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f  _OPEN_NOMUTEX] o
1d1b0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  r [SQLITE_OPEN_F
1d1c0 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a  ULLMUTEX] flags:
1d1d0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
1d1e0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1d1f0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1d200 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1d210 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1d220 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1d230 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1d240 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1d250 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1d260 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1d270 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d280 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1d290 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
1d2a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d2b0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1d2c0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1d2d0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
1d2e0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
1d2f0 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
1d300 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1d310 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1d320 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
1d330 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
1d340 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
1d350 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1d360 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
1d370 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d380 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
1d390 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d3a0 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1d3b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1d3c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1d3d0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1d3e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1d3f0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1d400 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a   creates it if.*
1d410 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
1d420 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
1d430 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
1d440 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
1d450 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
1d460 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1d470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d480 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
1d490 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1d4a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d4b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1d4c0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1d4d0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1d4e0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
1d4f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
1d500 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1d510 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
1d520 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
1d530 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1d540 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1d550 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73  FULLMUTEX] flags
1d560 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
1d570 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1d580 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
1d590 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1d5a0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1d5b0 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1d5c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d5d0 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1d5e0 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1d5f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1d600 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1d610 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1d620 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1d630 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1d640 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1d650 69 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  ime.  If the.** 
1d660 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d670 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1d680 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1d690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d6a0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1d6b0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1d6c0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1d6d0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1d6e0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1d6f0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1d700 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1d710 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  start-time..**.*
1d720 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
1d730 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1d740 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1d750 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1d760 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1d770 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1d780 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1d790 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20   This in-memory 
1d7a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1d7b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1d7c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d7d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1d7e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1d7f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1d800 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1d810 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1d820 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1d830 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1d840 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1d850 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1d860 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1d870 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1d880 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1d890 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1d8a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1d8b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1d8c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1d8d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1d8e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1d8f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1d900 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1d910 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1d920 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1d930 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1d940 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1d950 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1d960 65 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73  e created.  This
1d970 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1d980 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1d990 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1d9a0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1d9b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d9c0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1d9d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
1d9e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
1d9f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1da00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1da10 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1da20 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
1da30 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
1da40 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1da50 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
1da60 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1da70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
1da80 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20  ld use.  If the 
1da90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1daa0 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
1dab0 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
1dac0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1dad0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
1dae0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  sed..**.** <b>No
1daf0 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1db00 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1db10 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1db20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1db30 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1db40 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1db50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1db60 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1db70 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1db80 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1db90 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1dba0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1dbb0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1dbc0 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1dbd0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1dbe0 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1dbf0 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1dc00 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1dc10 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1dc20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1dc30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1dc40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20  .**.** {H12701} 
1dc50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1dc60 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1dc70 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1dc80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1dc90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1dca0 74 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20  terfaces create 
1dcb0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1dcc0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1dcd0 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  ection] associat
1dce0 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ed with.**      
1dcf0 20 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65      the database
1dd00 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74   file given in t
1dd10 68 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d  heir first param
1dd20 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
1dd30 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d  702} The filenam
1dd40 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1dd50 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1dd60 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  -8.**          f
1dd70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1dd80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1dd90 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20  _open_v2()] and 
1dda0 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  as UTF-16.**    
1ddb0 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
1ddc0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
1ddd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
1dde0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
1ddf0 32 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66  2703} A successf
1de00 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
1de10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1de20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1de30 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1de40 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1de50 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73  pen_v2()] writes
1de60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1de70 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1de80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1de90 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62  tion] into *ppDb
1dea0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d  ..**.** {H12704}
1deb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1dec0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1ded0 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1dee0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1def0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1df00 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1df10 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f   [SQLITE_OK] upo
1df20 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20  n success,.**   
1df30 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70         or an app
1df40 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
1df50 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65  code] on failure
1df60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d  ..**.** {H12706}
1df70 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1df80 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1df90 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1dfa0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1dfb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dfc0 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  _open()] or [sql
1dfd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1dfe0 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a  will be UTF-8..*
1dff0 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68  *.** {H12707} Th
1e000 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65  e default text e
1e010 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65  ncoding for a ne
1e020 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74  w database creat
1e030 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
1e040 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1e050 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20  en16()] will be 
1e060 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48  UTF-16..**.** {H
1e070 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  12709} The [sqli
1e080 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69  te3_open(F,D)] i
1e090 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69  nterface is equi
1e0a0 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  valent to.**    
1e0b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1e0c0 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d  pen_v2(F,D,G,0)]
1e0d0 20 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72   where the G par
1e0e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
1e0f0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50        [SQLITE_OP
1e100 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53  EN_READWRITE]|[S
1e110 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e120 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  E]..**.** {H1271
1e130 31 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  1} If the G para
1e140 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1e150 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e160 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1e170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1e180 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1e190 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68  PEN_READONLY] th
1e1a0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e1b0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1e1c0 20 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e        for readin
1e1d0 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g only..**.** {H
1e1e0 31 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20  12712} If the G 
1e1f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1e200 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1e210 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1e220 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e230 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1e240 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1e250 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  E] then the data
1e260 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a  base is opened.*
1e270 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69  *          readi
1e280 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1e290 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66  f possible, or f
1e2a0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20  or reading only 
1e2b0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
1e2c0 20 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65     file is write
1e2d0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1e2e0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e2f0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  em..**.** {H1271
1e300 33 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  3} If the G para
1e310 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1e320 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e330 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a  V)] omits the.**
1e340 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1e350 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1e360 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
1e370 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1e380 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
1e390 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
1e3a0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1e3b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  urned..**.** {H1
1e3c0 32 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70  2714} If the G p
1e3d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1e3e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1e3f0 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1e400 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e410 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1e420 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1e430 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1e440 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1e450 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1e460 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61  exist, then an a
1e470 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1e480 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20  o create and.** 
1e490 20 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c           initial
1e4a0 69 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ize the database
1e4b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d  ..**.** {H12717}
1e4c0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1e4d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1e4e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1e4f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1e500 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
1e510 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1e520 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72  v2()] is ":memor
1e530 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69  y:", then an pri
1e540 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1e550 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d    ephemeral, in-
1e560 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
1e570 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1e580 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  he connection..*
1e590 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1e5a0 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >Is SQLITE_OPEN_
1e5b0 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50  CREATE|SQLITE_OP
1e5c0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71  EN_READWRITE req
1e5d0 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  uired.**        
1e5e0 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65    in sqlite3_ope
1e5f0 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a  n_v2()?</todo>.*
1e600 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66  *.** {H12719} If
1e610 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1e620 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
1e630 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1e640 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1e650 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20        ephemeral 
1e660 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1e670 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1e680 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1e690 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1e6a0 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1e6b0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e6c0 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1e6d0 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1e6e0 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1e6f0 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d  >.**.** {H12721}
1e700 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
1e710 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74  onnection] creat
1e720 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f  ed by [sqlite3_o
1e730 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1e740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
1e750 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  l use the [sqlit
1e760 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1e770 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
1e780 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a   V parameter,.**
1e790 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
1e7a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1e7b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66  3_vfs] object if
1e7c0 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   V is a NULL poi
1e7d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nter..**.** {H12
1e7e0 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61  723} Two [databa
1e7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
1e800 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d  will share a com
1e810 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74  mon cache if bot
1e820 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20  h were.**       
1e830 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74     opened with t
1e840 68 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c  he same VFS whil
1e850 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1e860 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65  mode] was enable
1e870 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  d and.**        
1e880 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61    if both filena
1e890 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61  mes compare equa
1e8a0 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29  l using memcmp()
1e8b0 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65   after having be
1e8c0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  en.**          p
1e8d0 72 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20  rocessed by the 
1e8e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78  [sqlite3_vfs | x
1e8f0 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65  FullPathname] me
1e900 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e  thod of the VFS.
1e910 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e920 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1e930 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1e940 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1e950 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1e960 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1e970 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1e980 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1e990 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1e9a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1e9b0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1e9c0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1e9d0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1e9e0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1e9f0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1ea00 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1ea10 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1ea20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1ea30 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1ea40 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1ea50 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1ea60 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1ea70 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1ea80 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1ea90 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1eaa0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1eab0 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1eac0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1ead0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1eae0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1eaf0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1eb00 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1eb10 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
1eb20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
1eb30 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30  es {H12800} <S60
1eb40 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
1eb50 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1eb60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1eb70 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1eb80 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1eb90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1eba0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1ebb0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1ebc0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1ebd0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1ebe0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1ebf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ec00 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1ec10 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1ec20 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1ec30 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1ec40 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1ec50 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1ec60 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1ec70 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1ec80 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
1ec90 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1eca0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1ecb0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
1ecc0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
1ecd0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
1ece0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1ecf0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
1ed00 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
1ed10 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
1ed20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1ed30 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
1ed40 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
1ed50 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
1ed60 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1ed70 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
1ed80 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
1ed90 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
1eda0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1edb0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1edc0 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   Memory to hold 
1edd0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
1ede0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
1edf0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
1ee00 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1ee10 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
1ee20 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
1ee30 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
1ee40 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
1ee50 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
1ee60 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
1ee70 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
1ee80 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
1ee90 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
1eea0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
1eeb0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
1eec0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
1eed0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1eee0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
1eef0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
1ef00 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
1ef10 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
1ef20 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
1ef30 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
1ef40 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
1ef50 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
1ef60 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
1ef70 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
1ef80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
1ef90 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
1efa0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
1efb0 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
1efc0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
1efd0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
1efe0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
1eff0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
1f000 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
1f010 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
1f020 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
1f030 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
1f040 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1f050 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
1f060 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1f070 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
1f080 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1f090 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
1f0a0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
1f0b0 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
1f0c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
1f0d0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
1f0e0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
1f0f0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
1f100 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
1f110 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
1f120 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
1f130 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
1f140 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
1f150 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
1f160 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
1f170 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
1f180 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
1f190 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
1f1a0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
1f1b0 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
1f1c0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
1f1d0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
1f1e0 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49   be set..**.** I
1f1f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1f200 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {H12801} The [s
1f210 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
1f220 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1f230 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1f240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65  .**          [re
1f250 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
1f260 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1f270 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1f280 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1f290 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1f2a0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1f2b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1f2c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f2d0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1f2e0 7b 48 31 32 38 30 32 7d 20 54 68 65 20 5b 73 71  {H12802} The [sq
1f2f0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f300 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72  rrcode(D)] inter
1f310 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1f320 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20   numeric.**     
1f330 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72       [extended r
1f340 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1f350 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1f360 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61  y.**          fa
1f370 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1f380 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
1f390 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1f3a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
1f3b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20  .**.** {H12803} 
1f3c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
1f3d0 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c  msg(D)] and [sql
1f3e0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29  ite3_errmsg16(D)
1f3f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1f400 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1f410 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1f420 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
1f430 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ibes.**         
1f440 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68   the error in th
1f450 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c  e mostly recentl
1f460 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61  y failed interfa
1f470 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20  ce call,.**     
1f480 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20       encoded as 
1f490 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1f4a0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1f4b0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ely..**.** {H128
1f4c0 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  07} The strings 
1f4d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1f4e0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
1f4f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
1f500 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  sg16()].**      
1f510 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e      are valid un
1f520 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c  til the next SQL
1f530 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63 61  ite interface ca
1f540 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  ll..**.** {H1280
1f550 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20  8} Calls to API 
1f560 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f  routines that do
1f570 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65   not return an e
1f580 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
1f590 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20        (example: 
1f5a0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
1f5b0 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a  unt()]) do not.*
1f5c0 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67  *          chang
1f5d0 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  e the error code
1f5e0 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75   or message retu
1f5f0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1f600 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
1f610 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
1f620 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1f630 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  de()],.**       
1f640 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d     [sqlite3_errm
1f650 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1f660 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1f670 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49  **.** {H12809} I
1f680 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1f690 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1f6a0 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1f6b0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1f6c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f6d0 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1f6e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f6f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1f700 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1f710 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1f720 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1f730 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1f740 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1f750 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1f760 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f770 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  )], [sqlite3_ext
1f780 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
1f790 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1f7a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1f7b0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1f7c0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  rmsg16()]..*/.in
1f7d0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1f7e0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1f7f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
1f800 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
1f810 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
1f820 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
1f830 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
1f840 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1f850 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1f860 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1f870 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1f880 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
1f890 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e  H13000} <H13010>
1f8a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1f8b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f8c0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
1f8d0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
1f8e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
1f8f0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
1f900 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
1f910 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
1f920 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
1f930 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
1f940 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
1f950 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
1f960 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
1f970 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
1f980 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
1f990 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
1f9a0 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
1f9b0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
1f9c0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
1f9d0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
1f9e0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
1f9f0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1fa00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fa10 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
1fa20 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
1fa30 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
1fa40 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
1fa50 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
1fa60 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
1fa70 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
1fa80 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
1fa90 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
1faa0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
1fab0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
1fac0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
1fad0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
1fae0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
1faf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
1fb00 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
1fb10 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
1fb20 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
1fb30 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
1fb40 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
1fb50 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
1fb60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1fb70 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
1fb80 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
1fb90 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
1fba0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
1fbb0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
1fbc0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
1fbd0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
1fbe0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1fbf0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
1fc00 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
1fc10 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
1fc20 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d   Limits {H12760}
1fc30 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20600>.**.** 
1fc40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1fc50 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1fc60 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1fc70 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1fc80 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1fc90 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1fca0 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1fcb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1fcc0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1fcd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1fce0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1fcf0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1fd00 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1fd10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1fd20 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1fd30 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1fd40 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1fd50 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1fd60 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1fd70 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1fd80 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1fd90 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1fda0 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1fdb0 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1fdc0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1fdd0 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
1fde0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1fdf0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1fe00 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1fe10 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1fe20 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
1fe30 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1fe40 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1fe50 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70  re is a hard upp
1fe60 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20  er.** bound set 
1fe70 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  by a compile-tim
1fe80 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  e C preprocessor
1fe90 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1fea0 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1feb0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1fec0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1fed0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1fee0 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1fef0 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1ff00 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1ff10 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1ff20 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1ff30 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1ff40 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1ff50 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1ff60 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1ff70 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1ff80 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1ff90 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1ffa0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1ffb0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1ffc0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1ffd0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1ffe0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1fff0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
20000 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
20010 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
20020 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
20030 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
20040 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
20050 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
20060 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
20070 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
20080 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
20090 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
200a0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
200b0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
200c0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
200d0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
200e0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
200f0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
20100 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
20110 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
20120 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
20130 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
20140 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
20150 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
20160 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
20170 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
20180 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
20190 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
201a0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
201b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
201c0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
201d0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
201e0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
201f0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
20200 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20210 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
20220 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
20230 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
20240 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
20250 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
20260 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
20270 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
20280 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
20290 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
202a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
202b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
202c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32  S:.**.** {H12762
202d0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
202e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
202f0 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
20300 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20  ere V is.**     
20310 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68       positive ch
20320 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20  anges the limit 
20330 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
20340 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68  onstruct C in th
20350 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
20360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20370 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73  on] D to the les
20380 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65  ser of V and the
20390 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20   hard upper.**  
203a0 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e          bound on
203b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74   the size of C t
203c0 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f  hat is set at co
203d0 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile-time..**.*
203e0 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63  * {H12766} A suc
203f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
20400 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
20410 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
20420 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
20430 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68         leaves th
20440 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b  e state of the [
20450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20460 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
20470 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d  ..**.** {H12769}
20480 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
20490 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
204a0 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
204b0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
204c0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
204d0 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
204e0 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
204f0 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20   C in the.**    
20500 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
20510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73  connection] D as
20520 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f   it was prior to
20530 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e   the call..*/.in
20540 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
20550 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
20560 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
20570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20580 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
20590 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39  ategories {H1279
205a0 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b  0} <H12760>.** K
205b0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
205c0 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74  category} {limit
205d0 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
205e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
205f0 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
20600 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b  s aspects of a [
20610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20620 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e  ion].** that can
20630 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73   be limited in s
20640 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ize by calls to 
20650 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20660 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e  ]..** The meanin
20670 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
20680 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20  s limits are as 
20690 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
206a0 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
206b0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
206c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
206d0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
206e0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
206f0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c  B or table row.<
20700 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20710 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
20720 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
20730 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
20740 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
20750 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
20760 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20770 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
20780 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20790 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
207a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
207b0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
207c0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
207d0 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54   set of a SELECT
207e0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
207f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20800 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
20810 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
20820 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
20830 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  lause.</dd>.**.*
20840 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20850 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
20860 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20870 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
20880 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
20890 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
208a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
208b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
208c0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
208d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
208e0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
208f0 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
20900 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
20910 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
20920 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20930 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
20940 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20950 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
20960 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
20970 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
20980 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
20990 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
209a0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
209b0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
209c0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
209d0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
209e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
209f0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
20a00 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
20a10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
20a20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
20a30 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
20a40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
20a50 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
20a60 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a  databases.</dd>.
20a70 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
20a80 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
20a90 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
20aa0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20ab0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
20ac0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
20ad0 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72  t to the LIKE or
20ae0 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f  .** GLOB operato
20af0 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  rs.</dd>.**.** <
20b00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20b10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
20b20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20b30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20b40 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61  f variables in a
20b50 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
20b60 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62  that can.** be b
20b70 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ound.</dd>.** </
20b80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
20b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
20ba0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20bb0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
20bc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
20bd0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
20be0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
20bf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20c00 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
20c10 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
20c20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
20c30 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
20c40 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
20c50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20c60 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
20c70 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
20c80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20c90 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
20ca0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
20cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20cc0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
20cd0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#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 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
20d00 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
20d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20d20 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
20d30 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
20d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20d50 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
20d60 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
20d70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20d80 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
20d90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  QL Statement {H1
20da0 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  3010} <S10000>.*
20db0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
20dc0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
20dd0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
20de0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
20df0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
20e00 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
20e10 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
20e20 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
20e30 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
20e40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
20e50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
20e60 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
20e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20e80 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
20e90 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20  a.** prior call 
20ea0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
20eb0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
20ec0 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  en_v2()] or [sql
20ed0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
20ee0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
20ef0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
20f00 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
20f10 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
20f20 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
20f30 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
20f40 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
20f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
20f60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
20f70 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
20f80 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
20f90 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
20fa0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
20fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20fc0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
20fd0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  -16..**.** If th
20fe0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
20ff0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
21000 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
21010 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
21020 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
21030 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79  rminator. If nBy
21040 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
21050 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
21060 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
21070 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
21080 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
21090 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
210a0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
210b0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
210c0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
210d0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
210e0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
210f0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
21100 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
21110 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
21120 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
21130 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
21140 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
21150 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
21160 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
21170 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
21180 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
21190 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
211a0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
211b0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
211c0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
211d0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
211e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
211f0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
21200 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
21210 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
21220 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
21230 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  * *pzTail is mad
21240 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
21250 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
21260 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
21270 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
21280 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
21290 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
212a0 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68   only compile th
212b0 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65  e first.** state
212c0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
212d0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
212e0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61   pointing to wha
212f0 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63  t remains.** unc
21300 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
21310 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
21320 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
21330 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
21340 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
21350 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
21360 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
21370 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74  3_step()].  If t
21380 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
21390 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
213a0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66  .** to NULL.  If
213b0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
213c0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
213d0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
213e0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
213f0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
21400 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
21410 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
21420 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63  * {A13018} The c
21430 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
21440 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
21450 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
21460 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
21470 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
21480 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21490 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
214a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
214b0 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
214c0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
214d0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20  K] is returned, 
214e0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
214f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21500 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
21510 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21520 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
21530 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21540 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
21550 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
21560 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
21570 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
21580 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
21590 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
215a0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
215b0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
215c0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
215d0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
215e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
215f0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
21600 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
21610 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
21620 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
21630 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
21640 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
21650 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
21660 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
21670 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
21680 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
21690 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
216a0 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
216b0 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
216c0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
216d0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
216e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
216f0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
21700 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
21710 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
21720 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
21730 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21740 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
21750 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
21760 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
21770 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
21780 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
21790 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
217a0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
217b0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
217c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
217d0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
217e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
217f0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
21800 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
21810 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
21820 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
21830 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
21840 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
21850 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
21860 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
21870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21880 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
21890 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
218a0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
218b0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
218c0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
218d0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
218e0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
218f0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
21900 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
21910 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
21920 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
21930 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
21940 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
21950 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
21960 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
21970 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
21980 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
21990 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
219a0 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63  des].  The legac
219b0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
219c0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
219d0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
219e0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
219f0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
21a00 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
21a10 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  * and you would 
21a20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
21a30 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
21a40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21a50 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66  in order.** to f
21a60 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
21a70 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
21a80 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
21a90 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
21aa0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
21ab0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
21ac0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
21ad0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
21ae0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
21af0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
21b00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21b10 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68  *.** {H13011} Th
21b20 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21b30 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  re(db,zSql,...)]
21b40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
21b50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21b60 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  e_v2(db,zSql,...
21b70 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
21b80 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
21b90 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
21ba0 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
21bb0 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a  eter as UTF-8..*
21bc0 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68  *.** {H13012} Th
21bd0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21be0 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
21bf0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
21c00 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
21c10 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c  are16_v2(db,zSql
21c20 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
21c30 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
21c40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
21c50 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
21c60 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
21c70 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21c80 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
21c90 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74  ** {H13013} If t
21ca0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
21cb0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
21cc0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
21cd0 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
21ce0 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
21cf0 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
21d00 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
21d10 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
21d20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
21d30 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
21d40 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
21d50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
21d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20  .**.** {H13014} 
21d70 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
21d80 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
21d90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
21da0 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
21db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21dc0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
21dd0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
21de0 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
21df0 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20  es bytes of.**  
21e00 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74          SQL text
21e10 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53   is read from zS
21e20 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  ql..**.** {H1301
21e30 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70  5} In [sqlite3_p
21e40 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
21e50 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61  l,N,P,pzTail)] a
21e60 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  nd its variants.
21e70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
21e80 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65  he zSql input te
21e90 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65  xt contains more
21ea0 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74   than one SQL st
21eb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  atement.**      
21ec0 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69      and pzTail i
21ed0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
21ee0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
21ef0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
21f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
21f10 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
21f20 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
21f30 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
21f40 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20  in zSql..**     
21f50 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20       <todo>What 
21f60 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69  does *pzTail poi
21f70 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69  nt to if there i
21f80 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f  s one statement?
21f90 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
21fa0 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73  13016} A success
21fb0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
21fc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21fd0 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74  db,zSql,N,ppStmt
21fe0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
21ff0 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73     or one of its
22000 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73   variants writes
22010 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20   into *ppStmt a 
22020 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
22030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22050 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  ] or a pointer t
22060 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63  o NULL if zSql c
22070 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
22080 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65      nothing othe
22090 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
220a0 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a  e or comments..*
220b0 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68  *.** {H13019} Th
220c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
220d0 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  re_v2()] interfa
220e0 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  ce and its varia
220f0 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  nts return.**   
22100 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
22110 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  K] or an appropr
22120 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
22130 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  ] upon failure..
22140 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42  **.** {H13021} B
22150 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70  efore [sqlite3_p
22160 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e  repare(db,zSql,n
22170 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61  Byte,ppStmt,pzTa
22180 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20  il)] or its.**  
22190 20 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73          variants
221a0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
221b0 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  r (any value oth
221c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
221d0 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OK]),.**        
221e0 20 20 74 68 65 79 20 66 69 72 73 74 20 73 65 74    they first set
221f0 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c   *ppStmt to NULL
22200 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22210 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
22220 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
22230 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
22240 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22250 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
22260 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
22270 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
22280 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22290 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
222a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
222b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
222c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
222d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
222e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
222f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22300 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
22310 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22320 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22330 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22340 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
22350 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
22360 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22370 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22380 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
22390 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
223a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
223b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
223c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
223d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
223e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
223f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
22400 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
22410 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
22420 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
22430 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
22440 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22450 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
22460 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
22470 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
22480 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
22490 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
224a0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
224b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
224c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
224d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
224e0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
224f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22500 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
22510 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
22520 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
22530 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
22540 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
22550 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
22560 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
22570 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
22580 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22590 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
225a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
225b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
225c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
225d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
225e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
225f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22600 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22610 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22620 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
22630 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22640 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
22650 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
22660 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
22670 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22680 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22690 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
226a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
226b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
226c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
226d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
226e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
226f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22700 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22710 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
22720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
22730 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
22740 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20  nt SQL {H13100} 
22750 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H13000>.**.** T
22760 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
22770 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
22780 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
22790 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
227a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
227b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
227c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
227d0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
227e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
227f0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
22800 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
22810 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
22820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22830 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
22840 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
22850 7b 48 31 33 31 30 31 7d 20 49 66 20 74 68 65 20  {H13101} If the 
22860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22870 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
22880 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
22890 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
228a0 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
228b0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
228c0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
228d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
228e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
228f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22900 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ()], then [sqlit
22910 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e  e3_sql()] return
22920 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
22930 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
22940 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
22950 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  ing containing a
22960 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
22970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
22980 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  the original SQL
22990 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
229a0 2a 20 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68  * {H13102} If th
229b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
229c0 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73  ement] passed as
229d0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
229e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
229f0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
22a00 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
22a10 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
22a20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
22a30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22a40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
22a50 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
22a60 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20  ql()] returns a 
22a70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
22a80 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65  .** {H13103} The
22a90 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
22aa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   by [sqlite3_sql
22ab0 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e  (S)] is valid un
22ac0 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  til the.**      
22ad0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22ae0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65  atement] S is de
22af0 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  leted using [sql
22b00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
22b10 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
22b20 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
22b30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22b40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22b50 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
22b60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
22b70 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32  ect {H15000} <S2
22b80 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
22b90 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
22ba0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
22bb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22bc0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
22bd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
22be0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22bf0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
22c00 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
22c10 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
22c20 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
22c30 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
22c40 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
22c50 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
22c60 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
22c70 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
22c80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22c90 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
22ca0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
22cb0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
22cc0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
22cd0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
22ce0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
22cf0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
22d00 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
22d10 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
22d20 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
22d30 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
22d40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
22d50 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
22d60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
22d70 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
22d80 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
22d90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
22da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
22db0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
22dc0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
22dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
22de0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
22df0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
22e00 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
22e10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
22e20 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
22e30 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
22e40 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
22e50 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
22e60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
22e70 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
22e80 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
22e90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
22ea0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
22eb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22ec0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
22ed0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
22ee0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
22ef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22f00 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
22f10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
22f20 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
22f30 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
22f40 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
22f50 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
22f60 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
22f70 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
22f80 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
22f90 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
22fa0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
22fb0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
22fc0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
22fd0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
22fe0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
22ff0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
23000 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
23010 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
23020 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
23030 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
23040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
23050 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
23060 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
23070 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
23080 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
23090 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
230a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
230b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
230c0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
230d0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
230e0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
230f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
23100 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
23110 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23120 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
23130 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
23140 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
23150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23160 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
23170 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
23180 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
23190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
231a0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
231b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
231c0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
231d0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
231e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
231f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
23200 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23210 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
23220 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
23230 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23240 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
23250 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
23260 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
23270 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
23280 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
23290 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
232a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
232b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
232c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
232d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
232e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
232f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23300 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
23310 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
23320 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
23330 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
23340 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
23350 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
23360 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32  t {H16001} <S202
23370 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  00>.**.** The co
23380 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
23390 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
233a0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
233b0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
233c0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
233d0 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
233e0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
233f0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
23400 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
23410 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
23420 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23430 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
23440 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
23450 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
23460 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
23470 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
23480 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
23490 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
234a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
234b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
234c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
234d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
234e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
234f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
23500 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
23510 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
23520 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
23530 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
23540 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
23550 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
23560 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
23570 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23580 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
23590 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
235a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
235b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
235c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
235d0 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30   {H13500} <S7030
235e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
235f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
23600 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23610 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
23620 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
23630 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
23640 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
23650 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
23660 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
23670 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
23680 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
23690 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
236a0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
236b0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
236c0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
236d0 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  d by a parameter
236e0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
236f0 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
23700 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
23710 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
23720 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
23730 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
23740 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
23750 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
23760 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
23770 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
23780 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
23790 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
237a0 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
237b0 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
237c0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
237d0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
237e0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
237f0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
23800 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
23810 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
23820 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
23830 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23840 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
23850 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
23860 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
23870 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
23880 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23890 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
238a0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
238b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
238c0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
238d0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
238e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
238f0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
23900 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
23910 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
23920 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
23930 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
23940 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
23950 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
23960 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
23970 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
23980 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
23990 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
239a0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
239b0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
239c0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
239d0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
239e0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
239f0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
23a00 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
23a10 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
23a20 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
23a30 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
23a40 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
23a50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23a60 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
23a70 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
23a80 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
23a90 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
23aa0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
23ab0 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
23ac0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
23ad0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
23ae0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
23af0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
23b00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
23b10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
23b20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
23b30 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
23b40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
23b50 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
23b60 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
23b70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
23b80 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
23b90 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
23ba0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
23bb0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
23bc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
23bd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
23be0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
23bf0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
23c00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
23c10 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
23c20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
23c30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
23c40 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
23c50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23c60 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
23c70 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
23c80 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
23c90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23ca0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
23cb0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
23cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
23cd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
23ce0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
23cf0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
23d00 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
23d10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
23d20 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
23d30 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
23d40 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
23d50 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
23d60 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
23d70 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
23d80 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
23d90 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
23da0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
23db0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
23dc0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
23dd0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
23de0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
23df0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
23e00 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
23e10 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
23e20 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
23e30 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
23e40 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
23e50 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
23e60 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
23e70 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
23e80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
23e90 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
23ea0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
23eb0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
23ec0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
23ed0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
23ee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
23ef0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
23f00 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
23f10 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
23f20 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
23f30 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
23f40 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
23f50 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
23f60 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
23f70 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
23f80 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
23f90 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
23fa0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
23fb0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
23fc0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
23fd0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
23fe0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
23ff0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
24000 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
24010 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
24020 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
24030 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
24040 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
24050 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
24060 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
24070 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
24080 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
24090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
240a0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
240b0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
240c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
240d0 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
240e0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
240f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24100 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
24110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24120 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
24130 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
24140 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
24150 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
24160 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
24170 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
24180 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
24190 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
241a0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
241b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
241c0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
241d0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
241e0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
241f0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
24200 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
24210 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
24220 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
24230 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
24240 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
24250 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
24260 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
24270 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
24280 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
24290 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
242a0 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
242b0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
242c0 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
242d0 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
242e0 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
242f0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
24300 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
24310 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
24320 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
24330 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
24340 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
24350 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
24360 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
24370 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
24380 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
24390 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
243a0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
243b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
243c0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
243d0 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
243e0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
243f0 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
24400 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
24410 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
24420 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
24430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24440 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
24450 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24460 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
24470 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
24480 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NTS:.**.** {H135
24490 30 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61  06} The [SQL sta
244a0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
244b0 20 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65   recognizes toke
244c0 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a  ns of the forms.
244d0 2a 2a 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c  **          "?",
244e0 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
244f0 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
24500 56 56 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d  VV" as SQL param
24510 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20  eters,.**       
24520 20 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20     where NNN is 
24530 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
24540 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69  one or more digi
24550 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ts.**          a
24560 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
24570 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
24580 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68  one or more alph
24590 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20  anumeric.**     
245a0 20 20 20 20 20 63 68 61 72 61 63 74 65 72 73 20       characters 
245b0 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c  or "::" optional
245c0 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  ly followed by a
245d0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
245e0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ng.**          n
245f0 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e  o spaces and con
24600 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61  tained within pa
24610 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a  rentheses..**.**
24620 20 7b 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e   {H13509} The in
24630 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61  itial value of a
24640 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
24650 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
24660 48 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65  H13512} The inde
24670 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20  x of an "?" SQL 
24680 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
24690 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
246a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72  .**          lar
246b0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51  gest index of SQ
246c0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  L parameter to t
246d0 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66  he left, or 1 if
246e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
246f0 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74   "?" is the left
24700 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
24710 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31  er..**.** {H1351
24720 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  5} The index of 
24730 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61  an "?NNN" SQL pa
24740 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69  rameter is the i
24750 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a  nteger NNN..**.*
24760 2a 20 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69  * {H13518} The i
24770 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56  ndex of an ":VVV
24780 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40  ", "$VVV", or "@
24790 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74  VVV" SQL paramet
247a0 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
247b0 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68    the same as th
247c0 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d  e index of leftm
247d0 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20  ost occurrences 
247e0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
247f0 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
24800 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
24810 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
24820 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
24830 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24840 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
24850 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
24860 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
24870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
24880 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
24890 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
248a0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
248b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
248c0 48 31 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c  H13521} The [SQL
248d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
248e0 6c 65 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20  ler] fails with 
248f0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  an [SQLITE_RANGE
24900 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  ].**          er
24910 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65 78  ror if the index
24920 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
24930 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
24940 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n 1.**          
24950 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
24960 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
24970 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
24980 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20  ABLE_NUMBER.**  
24990 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
249a0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34  r..**.** {H13524
249b0 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
249c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
249d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
249e0 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,V,...)].**     
249f0 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74       associate t
24a00 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20  he value V with 
24a10 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
24a20 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20  rs having an.** 
24a30 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f           index o
24a40 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70  f N in the [prep
24a50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24a60 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37  S..**.** {H13527
24a70 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
24a80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
24a90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
24aa0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
24ab0 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f     override prio
24ac0 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65  r calls with the
24ad0 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20   same values of 
24ae0 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  S and N..**.** {
24af0 48 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73  H13530} Bindings
24b00 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20   established by 
24b10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24b20 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
24b30 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  d(S,...)].**    
24b40 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63        persist ac
24b50 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ross calls to [s
24b60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
24b70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d  ..**.** {H13533}
24b80 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24b90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24ba0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24bb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24bc0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24bd0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24be0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24bf0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24c00 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
24c10 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20  binds the first 
24c20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  L.**          by
24c30 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
24c40 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  or string pointe
24c50 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20  d to by V, when 
24c60 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  L.**          is
24c70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
24c80 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e  *.** {H13536} In
24c90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
24ca0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
24cb0 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20  ,V,L,D)] or.**  
24cc0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24cd0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24ce0 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
24cf0 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73  binds characters
24d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
24d10 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20  m V through the 
24d20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
24d30 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e  cter when L is n
24d40 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
24d50 48 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73  H13539} In calls
24d60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24d70 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
24d80 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
24d90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24da0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
24db0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
24dc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24dd0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
24de0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
24df0 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
24e00 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
24e10 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69  TE_STATIC], SQLi
24e20 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
24e30 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20  the value V.**  
24e40 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20          is held 
24e50 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61  in static unmana
24e60 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77  ged space that w
24e70 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a  ill not change.*
24e80 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e  *          durin
24e90 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
24ea0 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a  f the binding..*
24eb0 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e  *.** {H13542} In
24ec0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
24ed0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
24ee0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
24ef0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24f00 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
24f10 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
24f20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
24f30 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
24f40 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
24f50 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
24f60 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
24f70 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
24f80 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65  NT], the routine
24f90 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20   makes a.**     
24fa0 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70       private cop
24fb0 79 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56  y of the value V
24fc0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
24fd0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34  ns..**.** {H1354
24fe0 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  5} In calls to [
24ff0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25000 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
25010 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25020 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
25030 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
25040 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
25050 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
25060 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
25070 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  D is a pointer t
25080 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  o.**          a 
25090 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
250a0 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75   invokes that fu
250b0 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f  nction to destro
250c0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
250d0 20 20 76 61 6c 75 65 20 56 20 61 66 74 65 72 20    value V after 
250e0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
250f0 75 73 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  using the value 
25100 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38  V..**.** {H13548
25110 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
25120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
25130 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74  blob(S,N,V,L)] t
25140 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a  he value bound.*
25150 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20  *          is a 
25160 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c  BLOB of L bytes,
25170 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   or a zero-lengt
25180 68 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e  h BLOB if L is n
25190 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
251a0 48 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73  H13551} In calls
251b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
251c0 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20  d_value(S,N,V)] 
251d0 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d  the V argument m
251e0 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ay.**          b
251f0 65 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74  e either a [prot
25200 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25210 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61  lue] object or a
25220 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75  n.**          [u
25230 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25240 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
25250 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25260 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
25270 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
25280 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
25290 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
252a0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
252b0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
252c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
252d0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
252e0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
252f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25300 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
25310 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
25320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25330 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
25340 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
25350 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
25360 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
25370 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
25380 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
25390 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
253a0 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
253b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
253c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
253d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
253e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
253f0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
25400 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
25410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25420 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
25430 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
25440 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
25450 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
25460 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
25470 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
25480 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
25490 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
254a0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48  QL Parameters {H
254b0 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13600} <S70300>.
254c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
254d0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
254e0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
254f0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
25500 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
25510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25520 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
25530 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
25540 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
25550 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
25560 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
25570 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
25580 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
25590 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
255a0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
255b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
255c0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
255d0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
255e0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
255f0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
25600 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
25610 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
25620 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
25630 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
25640 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
25650 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
25660 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
25670 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
25680 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
25690 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
256a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
256b0 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  N are used,.** t
256c0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
256d0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a   in the list..**
256e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
256f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25700 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25710 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25720 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25730 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
25740 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25750 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25760 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25770 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20  .**.** {H13601} 
25780 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
25790 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
257a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
257b0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
257c0 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20      the largest 
257d0 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c  index of all SQL
257e0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74   parameters in t
257f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
25800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25810 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53  nt] S, or 0 if S
25820 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
25830 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
25840 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25850 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
25860 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
25870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25880 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
25890 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
258a0 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
258b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
258c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
258d0 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
258e0 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
258f0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
25900 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25910 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
25920 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
25930 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
25940 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
25950 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
25960 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
25970 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
25980 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
25990 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
259a0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
259b0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
259c0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
259d0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
259e0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
259f0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
25a00 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
25a10 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
25a20 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
25a30 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
25a40 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
25a50 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
25a60 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
25a70 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
25a80 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
25a90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
25aa0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
25ab0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
25ac0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
25ad0 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
25ae0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
25af0 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
25b00 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
25b10 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
25b20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
25b30 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
25b40 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
25b50 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
25b60 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
25b70 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
25b80 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
25b90 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
25ba0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
25bb0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
25bc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25bd0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
25be0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25bf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
25c00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25c10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25c20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25c30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25c40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25c50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25c60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
25c70 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68  *.** {H13621} Th
25c80 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25c90 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53  parameter_name(S
25ca0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25cb0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
25cc0 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65     a UTF-8 rende
25cd0 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65  ring of the name
25ce0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
25cf0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20  meter in.**     
25d00 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
25d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25d20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20  having index N, 
25d30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  or.**          N
25d40 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20  ULL if there is 
25d50 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
25d60 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72   with index N or
25d70 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
25d80 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69      parameter wi
25d90 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e  th index N is an
25da0 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d   anonymous param
25db0 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e  eter "?"..*/.con
25dc0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25dd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25de0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25df0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
25e00 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
25e10 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
25e20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
25e30 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33  e {H13640} <S703
25e40 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
25e50 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
25e60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
25e70 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
25e80 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
25e90 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
25ea0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
25eb0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
25ec0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
25ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25ee0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25ef0 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
25f00 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
25f10 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
25f20 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
25f30 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
25f40 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
25f50 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
25f60 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
25f70 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
25f80 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
25f90 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
25fa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25fb0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
25fc0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25fd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25fe0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
25ff0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26000 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
26010 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26020 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26030 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
26040 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26050 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65  .** {H13641} The
26060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26070 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
26080 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
26090 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
260a0 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
260b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
260c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
260d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
260e0 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61        S whose na
260f0 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55  me matches the U
26100 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f  TF-8 string N, o
26110 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a  r 0 if there is.
26120 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d  **          no m
26130 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  atch..*/.int sql
26140 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26150 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
26160 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
26170 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
26180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
26190 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
261a0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
261b0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
261c0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
261d0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
261e0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
261f0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
26200 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
26210 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
26220 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
26230 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
26240 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26250 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
26260 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
26270 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
26280 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
26290 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
262a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d  :.**.** {H13661}
262b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   The [sqlite3_cl
262c0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d  ear_bindings(S)]
262d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
262e0 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20  s all SQL.**    
262f0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
26300 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20  bindings in the 
26310 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26320 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e  ent] S back to N
26330 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
26340 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
26350 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
26360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26370 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
26380 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
26390 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c  t Set {H13710} <
263a0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
263b0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
263c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
263d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
263e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
263f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26400 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69  ent]. This routi
26410 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
26420 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
26430 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
26440 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
26450 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
26460 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
26470 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
26480 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31  TS:.**.** {H1371
26490 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
264a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
264b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
264c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
264d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
264e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
264f0 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
26500 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 65   by the [prepare
26510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a  d statement] S,.
26520 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 30  **          or 0
26530 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67   if S does not g
26540 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c 74  enerate a result
26550 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
26560 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
26570 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
26580 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26590 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
265a0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
265b0 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
265c0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
265d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
265e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
265f0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
26600 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
26610 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
26620 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26630 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
26640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26650 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
26660 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
26670 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
26680 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26690 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
266a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
266b0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
266c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
266d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
266e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
266f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26700 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
26710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26720 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
26730 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
26740 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
26750 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
26760 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
26770 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
26780 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
26790 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
267a0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
267b0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
267c0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
267d0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
267e0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
267f0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
26800 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26810 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
26820 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
26830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26840 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
26850 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26860 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
26870 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
26880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
26890 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
268a0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
268b0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
268c0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
268d0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
268e0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
268f0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
26900 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
26910 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
26920 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
26930 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
26940 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
26950 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
26960 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
26970 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
26980 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
26990 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
269a0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
269b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
269c0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
269d0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
269e0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
269f0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
26a00 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
26a10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26a20 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41  **.** {H13721} A
26a30 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
26a40 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
26a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26a60 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  me(S,N)].**     
26a70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72       interface r
26a80 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20  eturns the name 
26a90 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  of the Nth colum
26aa0 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a  n (where 0 is.**
26ab0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65            the le
26ac0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  ftmost column) f
26ad0 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  or the result se
26ae0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  t of the.**     
26af0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
26b00 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
26b10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26b20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
26b30 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20  *.** {H13723} A 
26b40 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
26b50 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
26b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26b70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
26b80 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
26b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
26ba0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
26bb0 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
26bc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
26bd0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
26be0 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
26bf0 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
26c00 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
26c10 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
26c20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26c30 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  d UTF-16 string.
26c40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
26c50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
26c60 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
26c70 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  724} The [sqlite
26c80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
26c90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
26ca0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a  lumn_name16()].*
26cb0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
26cc0 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
26cd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74  ULL pointer if t
26ce0 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74  hey are unable t
26cf0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  o.**          al
26d00 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
26d10 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d   hold their norm
26d20 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67  al return string
26d30 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35  s..**.** {H13725
26d40 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d  } If the N param
26d50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
26d60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
26d70 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
26d80 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26d90 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
26da0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
26db0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  then the.**     
26dc0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
26dd0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
26de0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
26df0 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67  3726} The string
26e00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
26e10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26e20 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20  me(S,N)] and.** 
26e30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
26e40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26e50 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20  S,N)] are valid 
26e60 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
26e70 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20  *          call 
26e80 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  to either routin
26e90 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  e with the same 
26ea0 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65  S and N paramete
26eb0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  rs.**          o
26ec0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
26ed0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
26ee0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   called..**.** {
26ef0 48 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72  H13727} When a r
26f00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
26f10 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
26f20 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ment contains.**
26f30 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53 20            an AS 
26f40 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65  clause, the name
26f50 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   of that column 
26f60 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69 65  is the identifie
26f70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
26f80 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74 68   the right of th
26f90 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f  e AS keyword..*/
26fa0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26fb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26fc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26fd0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
26fe0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
26ff0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
27000 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27020 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
27030 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
27040 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30  lt {H13740} <S10
27050 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700>.**.** These
27060 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
27070 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
27080 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75  ermine what colu
27090 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61  mn of what.** ta
270a0 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74  ble in which dat
270b0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f  abase a result o
270c0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
270d0 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
270e0 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  m..** The name o
270f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
27100 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
27110 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
27120 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
27130 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27140 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
27150 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
27160 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
27170 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
27180 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
27190 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
271a0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
271b0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
271c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
271d0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
271e0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
271f0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
27200 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
27210 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
27220 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
27230 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
27240 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
27250 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
27260 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
27270 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
27280 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
27290 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
272a0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
272b0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
272c0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
272d0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
272e0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
272f0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
27300 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27310 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
27320 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
27330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27340 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
27350 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
27360 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
27370 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
27380 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
27390 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
273a0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
273b0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
273c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
273d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
273e0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
273f0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
27400 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
27410 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
27420 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
27430 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
27440 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
27450 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54  turn.** NULL.  T
27460 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
27470 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
27480 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
27490 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
274a0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  .** occurs.  Oth
274b0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
274c0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
274d0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
274e0 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20  abase, table.** 
274f0 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  and column that 
27500 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
27510 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
27520 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
27530 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
27540 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
27550 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
27560 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
27570 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
27580 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
27590 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
275a0 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
275b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
275c0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
275d0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
275e0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
275f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
27600 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
27610 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
27620 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
27630 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
27640 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66  * {A13751}.** If
27650 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
27660 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
27670 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
27680 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
27690 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
276a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
276b0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
276c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
276d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
276e0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
276f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
27700 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54  **.** {H13741} T
27710 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
27720 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
27730 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27740 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27750 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27760 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
27770 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
27780 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
27790 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
277a0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
277b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
277c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
277d0 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
277e0 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
277f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
27800 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
27810 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
27820 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
27830 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
27840 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
27850 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
27860 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
27870 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  742} The [sqlite
27880 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
27890 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
278a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
278b0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
278c0 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
278d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
278e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
278f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
27900 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
27910 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65    from which the
27920 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27930 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27950 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
27960 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
27970 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27980 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27990 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
279a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
279b0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
279c0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
279d0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
279e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20  .**.** {H13743} 
279f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27a00 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
27a10 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27a20 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27a30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27a40 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
27a50 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27a60 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
27a70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27a80 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27a90 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27ab0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
27ac0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
27ad0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27ae0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27af0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27b00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27b10 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27b20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27b30 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20  .**.** {H13744} 
27b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27b60 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
27b70 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27b80 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27b90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27ba0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
27bb0 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
27bc0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
27bd0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20   the table.**   
27be0 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
27bf0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
27c00 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
27c10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27c20 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
27c30 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
27c40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
27c50 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
27c60 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
27c70 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
27c80 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
27c90 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
27ca0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
27cb0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
27cc0 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  745} The [sqlite
27cd0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
27ce0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
27cf0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
27d00 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27d10 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
27d20 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27d30 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
27d40 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  mn from which th
27d50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
27d60 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
27d70 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
27d80 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
27d90 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
27da0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
27db0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
27dc0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
27dd0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
27de0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
27df0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27e00 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
27e10 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
27e20 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65  .** {H13746} The
27e30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27e40 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53  _origin_name16(S
27e50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27e60 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27e70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27e80 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
27e90 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
27ea0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27eb0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
27ec0 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d       column from
27ed0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
27ee0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
27ef0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
27f00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27f10 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
27f20 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
27f30 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a  the Nth column.*
27f40 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 53 20  *          of S 
27f50 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
27f60 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
27f70 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
27f80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
27f90 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
27fa0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
27fb0 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e  3748} The return
27fc0 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20   values from.** 
27fd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27fe0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
27ff0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
28000 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
28010 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
28020 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74   are valid for t
28030 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
28040 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28050 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
28060 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65      or until the
28070 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61   encoding is cha
28080 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20  nged by another 
28090 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
280a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
280b0 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
280c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
280d0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
280e0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
280f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31  S:.**.** {A13751
28100 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  } If two or more
28110 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28120 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
28130 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
28140 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28150 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
28160 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
28170 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  ].**          fo
28180 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
28190 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
281a0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
281b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
281c0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
281d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
281e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
281f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28200 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
28210 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
28220 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28230 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28240 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28250 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
28260 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
28270 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28280 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
28290 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
282a0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
282b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
282c0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
282d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
282e0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
282f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
28300 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
28310 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28320 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28330 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
28340 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28350 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
28370 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
28380 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
28390 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30   {H13760} <S1070
283a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0>.**.** The fir
283b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
283c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
283d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
283e0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
283f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
28400 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
28410 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
28420 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
28430 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
28440 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
28450 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
28460 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
28470 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
28480 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
28490 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
284a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
284b0 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e  urned.  If the N
284c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
284d0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
284e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
284f0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
28500 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
28510 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
28520 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
28530 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
28540 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45  TF-8 encoded. {E
28550 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ND}.**.** For ex
28560 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
28570 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
28580 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
28590 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
285a0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
285b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
285c0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
285d0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
285e0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
285f0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
28600 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
28610 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
28620 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
28630 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
28640 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
28650 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
28660 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
28670 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
28680 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  umn (i==0)..**.*
28690 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
286a0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
286b0 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
286c0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
286d0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
286e0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
286f0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
28700 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
28710 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
28720 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
28730 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
28740 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
28750 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
28760 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
28770 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
28780 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
28790 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
287a0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
287b0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
287c0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
287d0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
287e0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
287f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  es..**.** INVARI
28800 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
28810 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73 66  761}  A successf
28820 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
28830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28840 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  ype(S,N)] return
28850 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
28860 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28870 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
28880 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
28890 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a  lared datatype.*
288a0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  *           of t
288b0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
288c0 74 68 61 74 20 61 70 70 65 61 72 73 20 61 73 20  that appears as 
288d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
288e0 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20  numbered.**     
288f0 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66        from 0) of
28900 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28910 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
28920 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
28930 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41  *.** {H13762}  A
28940 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
28950 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
28960 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
28970 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
28980 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f    returns a zero
28990 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
289a0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
289b0 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20  rder string.**  
289c0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e           contain
289d0 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
289e0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
289f0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
28a00 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20  at appears.**   
28a10 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e          as the N
28a20 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
28a30 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74  red from 0) of t
28a40 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
28a50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28a60 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
28a70 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
28a80 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69  {H13763}  If N i
28a90 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72  s less than 0 or
28aa0 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 74 68   N is greater th
28ab0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a  an or equal to.*
28ac0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
28ad0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28ae0 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
28af0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
28b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
28b10 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
28b20 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78  mn of S is an ex
28b30 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
28b40 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20  uery rather.**  
28b50 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20           than a 
28b60 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72  table column, or
28b70 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
28b80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a  ocation failure.
28b90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
28ba0 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64  urs during encod
28bb0 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c  ing conversions,
28bc0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
28bd0 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c     calls to [sql
28be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
28bf0 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  type(S,N)] or.**
28c00 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
28c10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28c20 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75  ype16(S,N)] retu
28c30 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  rn NULL..*/.cons
28c40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28c50 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
28c60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28c70 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
28c80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28c90 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
28ca0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28cb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
28cc0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
28cd0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30  tatement {H13200
28ce0 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10000>.**.**
28cf0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
28d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
28d10 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
28d20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
28d30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28d40 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28d50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28d60 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
28d70 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
28d80 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
28d90 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
28da0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28db0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
28dc0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
28dd0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
28de0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
28df0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
28e00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
28e10 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
28e20 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
28e30 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
28e40 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
28e50 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
28e60 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
28e70 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
28e80 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
28e90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
28ea0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
28eb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28ec0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
28ed0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
28ee0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
28ef0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
28f00 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
28f10 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
28f20 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
28f30 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
28f40 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
28f50 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
28f60 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
28f70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
28f80 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
28f90 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
28fa0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
28fb0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
28fc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
28fd0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
28fe0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
28ff0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
29000 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
29010 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
29020 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
29030 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
29040 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
29050 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
29060 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
29070 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
29080 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
29090 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
290a0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
290b0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
290c0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
290d0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
290e0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
290f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
29100 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
29110 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
29120 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29130 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
29140 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
29150 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
29160 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
29170 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
29180 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
29190 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
291a0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
291b0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
291c0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
291d0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
291e0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
291f0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
29200 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
29210 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
29220 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  .**.** [SQLITE_D
29230 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
29240 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
29250 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
29260 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
29270 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
29280 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29290 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
292a0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
292b0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
292c0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
292d0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
292e0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
292f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
29300 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
29310 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
29320 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
29330 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
29340 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
29350 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
29360 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
29370 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
29380 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
29390 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
293a0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
293b0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
293c0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
293d0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
293e0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
293f0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
29400 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
29410 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
29420 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
29430 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
29440 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  data..**.** [SQL
29450 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
29460 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
29470 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
29480 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
29490 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
294a0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
294b0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
294c0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
294d0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
294e0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
294f0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
29500 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29510 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
29520 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
29530 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
29540 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29550 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
29560 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
29570 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
29580 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
29590 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
295a0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
295b0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
295c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
295d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
295e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
295f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
29600 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
29610 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
29620 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29630 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
29640 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
29650 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
29660 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
29670 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
29680 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
29690 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
296a0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
296b0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
296c0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
296d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
296e0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
296f0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
29700 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
29710 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
29720 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
29730 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
29740 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
29750 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
29760 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
29770 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
29780 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
29790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
297a0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
297b0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
297c0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
297d0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
297e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  me..**.** <b>Goo
297f0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
29800 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
29810 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29820 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
29830 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
29840 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
29850 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
29860 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
29870 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
29880 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
29890 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
298a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
298b0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
298c0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
298d0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
298e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
298f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
29900 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
29910 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29920 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
29930 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
29940 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
29950 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
29960 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
29970 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
29980 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
29990 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
299a0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
299b0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
299c0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
299d0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
299e0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
299f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
29a00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29a10 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
29a20 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
29a30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29a40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29a50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
29a60 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
29a70 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
29a80 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
29a90 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
29aa0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
29ab0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
29ac0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
29ad0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
29ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
29af0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29b00 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49  *.** {H13202}  I
29b10 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
29b20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
29b30 72 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c  ready to be run,
29b40 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
29b50 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
29b60 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68  (S)] advances th
29b70 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  at prepared stat
29b80 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20  ement until.**  
29b90 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74           complet
29ba0 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20  ion or until it 
29bb0 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  is ready to retu
29bc0 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
29bd0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
29be0 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f     result set, o
29bf0 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69  r until an [sqli
29c00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
29c10 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20  interrupt].**   
29c20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e          or a run
29c30 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75  -time error occu
29c40 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  rs..**.** {H1530
29c50 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  4}  When a call 
29c60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29c70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65 20  (S)] causes the 
29c80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29c90 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
29ca0 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f    S to run to co
29cb0 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75  mpletion, the fu
29cc0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
29cd0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a  SQLITE_DONE]..**
29ce0 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68  .** {H15306}  Wh
29cf0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
29d00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73  lite3_step(S)] s
29d10 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20  tops because it 
29d20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20  is ready to.**  
29d30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
29d40 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74  another row of t
29d50 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69  he result set, i
29d60 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  t returns [SQLIT
29d70 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  E_ROW]..**.** {H
29d80 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c  15308}  If a cal
29d90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29da0 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72  ep(S)] encounter
29db0 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  s an.**         
29dc0 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72    [sqlite3_inter
29dd0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
29de0 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20  ] or a run-time 
29df0 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
29e00 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61      it returns a
29e10 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
29e20 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73  ror code that is
29e30 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20   not one of.**  
29e40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29e50 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  _OK], [SQLITE_RO
29e60 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  W], or [SQLITE_D
29e70 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ONE]..**.** {H15
29e80 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c  310}  If an [sql
29e90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
29ea0 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
29eb0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a   run-time error.
29ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
29ed0 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c  urs during a cal
29ee0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29ef0 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ep(S)].**       
29f00 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61      for a [prepa
29f10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29f20 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
29f30 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61  *           lega
29f40 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  cy interfaces [s
29f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29f60 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
29f70 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
29f80 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
29f90 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
29fa0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
29fb0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
29fc0 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  RROR], [SQLITE_B
29fd0 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  USY], or [SQLITE
29fe0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74  _MISUSE]..*/.int
29ff0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2a000 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2a010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2a020 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2a030 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2a040 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30   {H13770} <S1070
2a050 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0>.**.** Returns
2a060 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
2a070 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
2a080 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2a090 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
2a0a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2a0b0 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66  .** {H13771}  Af
2a0c0 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
2a0d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a0e0 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
2a0f0 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20  LITE_ROW],.**   
2a100 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2a110 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a120 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  S)] routine will
2a130 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
2a140 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
2a150 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69      as the [sqli
2a160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2a170 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
2a180 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41  *.** {H13772}  A
2a190 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2a1a0 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
2a1b0 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
2a1c0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
2a1d0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
2a1e0 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
2a1f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2a200 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  as been called o
2a210 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2a220 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a230 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
2a240 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65  first time since
2a250 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20   it was.**      
2a260 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
2a270 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
2a280 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2a290 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a  set | reset],.**
2a2a0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
2a2b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a2c0 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72  nt(S)] routine r
2a2d0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
2a2e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2a2f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a300 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2a320 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2a330 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31  pes {H10265} <S1
2a340 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a  0110><S10120>.**
2a350 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2a360 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_TEXT.**.** {H1
2a370 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75  0266} Every valu
2a380 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2a390 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2a3a0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2a3b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2a3c0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2a3d0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2a3e0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2a3f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2a400 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2a410 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2a420 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2a430 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
2a440 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2a450 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2a460 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2a470 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2a480 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2a490 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2a4a0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2a4b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a4c0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2a4d0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2a4e0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2a4f0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2a500 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2a510 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2a520 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2a530 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2a540 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2a550 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2a560 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a570 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2a580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2a590 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2a5a0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2a5b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2a5c0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2a5d0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2a5e0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2a5f0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2a600 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2a610 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2a620 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2a630 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2a640 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2a650 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2a660 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37  y {H13800} <S107
2a670 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2a680 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2a690 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2a6a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a6b0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2a6c0 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
2a6d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
2a6e0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2a6f0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2a700 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2a710 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2a720 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2a730 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
2a740 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2a750 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a760 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2a770 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2a780 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a790 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2a7a0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2a7b0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2a7c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2a7d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2a7e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2a7f0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2a800 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2a810 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a820 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a830 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2a840 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2a850 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2a860 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ned.  The leftmo
2a870 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2a880 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2a890 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a  the index 0..**.
2a8a0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2a8b0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2a8c0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2a8d0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2a8e0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2a8f0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2a900 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2a910 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2a920 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2a930 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2a940 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2a950 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2a960 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a970 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2a980 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2a990 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2a9a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2a9b0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2a9c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2a9d0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2a9e0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2a9f0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2aa00 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2aa10 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2aa20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2aa30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2aa40 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2aa50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2aa60 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2aa70 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2aa80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2aa90 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2aaa0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2aab0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2aac0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2aad0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2aae0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2aaf0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2ab00 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2ab10 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2ab20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2ab30 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2ab40 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2ab50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2ab60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
2ab70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ab80 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2ab90 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2aba0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2abb0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2abc0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2abd0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2abe0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2abf0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
2ac00 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2ac10 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2ac20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2ac30 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2ac40 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2ac50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2ac60 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2ac70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2ac80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ac90 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2aca0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2acb0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2acc0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2acd0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2ace0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2acf0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2ad00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2ad10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ad20 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2ad30 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2ad40 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2ad50 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2ad60 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2ad70 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2ad80 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2ad90 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2ada0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
2adb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2adc0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2add0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ade0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2adf0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2ae00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2ae10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ae20 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2ae30 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
2ae40 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2ae50 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2ae60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ae70 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2ae80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2ae90 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2aea0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2aeb0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2aec0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2aed0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2aee0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2aef0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2af00 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2af10 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2af20 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2af30 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2af40 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2af50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2af60 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2af70 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
2af80 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
2af90 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2afa0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2afb0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2afc0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
2afd0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2afe0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2aff0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2b000 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2b010 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2b020 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2b030 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e  ers..**.** Strin
2b040 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2b050 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b060 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2b070 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2b080 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2b090 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2b0a0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
2b0b0 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
2b0c0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2b0d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b0e0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2b0f0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2b100 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
2b110 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
2b120 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
2b130 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
2b140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b150 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
2b160 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
2b170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b180 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
2b190 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
2b1a0 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
2b1b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
2b1c0 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
2b1d0 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** The zero term
2b1e0 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
2b1f0 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
2b200 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ount..**.** The 
2b210 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b220 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2b230 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2b240 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2b250 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2b260 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2b270 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b280 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2b290 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2b2a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2b2b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2b2c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2b2d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2b2e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2b2f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b300 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2b310 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2b320 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2b330 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2b340 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2b350 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2b360 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2b370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2b380 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2b390 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2b3a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2b3b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2b3c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2b3d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2b3e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2b3f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2b400 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2b410 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2b420 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
2b430 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2b440 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2b450 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2b460 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2b470 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2b480 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2b490 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2b4a0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2b4b0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2b4c0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2b4d0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
2b4e0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2b4f0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2b500 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2b510 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2b520 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2b530 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2b540 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2b550 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2b560 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2b570 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2b580 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2b590 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2b5a0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2b5b0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2b5c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b5d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b5e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2b5f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b600 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2b610 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2b620 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2b630 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b640 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2b650 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2b660 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2b670 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b680 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2b690 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2b6a0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2b6b0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2b6c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2b6d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2b6e0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2b6f0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2b700 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2b710 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2b720 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2b730 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2b740 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b750 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2b760 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b770 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2b780 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b790 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2b7a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b7b0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2b7c0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2b7d0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b7e0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b7f0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2b800 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2b810 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b820 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2b830 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2b840 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2b850 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b860 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2b870 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2b880 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2b890 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2b8a0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2b8b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2b8c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2b8d0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2b8e0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2b8f0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2b900 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b910 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2b920 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2b930 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2b940 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2b950 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b960 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2b970 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2b980 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2b990 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2b9a0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2b9b0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2b9c0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2b9d0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2b9e0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2b9f0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2ba00 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2ba10 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2ba20 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2ba30 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2ba40 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2ba50 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2ba60 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2ba70 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2ba80 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2ba90 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2baa0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2bab0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2bac0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2bad0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2bae0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2baf0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2bb00 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2bb10 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2bb20 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2bb30 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2bb40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bb50 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2bb60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bb70 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2bb80 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2bb90 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2bba0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2bbb0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2bbc0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2bbd0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2bbe0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2bbf0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bc00 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2bc10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bc20 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2bc30 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2bc40 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2bc50 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2bc60 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2bc70 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2bc80 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2bc90 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2bca0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2bcb0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2bcc0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2bcd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2bce0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2bcf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bd00 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2bd10 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2bd20 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2bd30 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2bd40 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2bd50 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bd60 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2bd70 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2bd80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2bd90 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2bda0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2bdb0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2bdc0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2bdd0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2bde0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2bdf0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
2be00 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2be10 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2be20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2be30 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2be40 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2be50 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2be60 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2be70 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2be80 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2be90 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2bea0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2beb0 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
2bec0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2bed0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2bee0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2bef0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2bf00 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2bf10 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2bf20 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2bf30 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2bf40 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2bf50 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2bf60 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2bf70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2bf80 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2bf90 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2bfa0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2bfb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2bfc0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2bfd0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2bfe0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2bff0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2c000 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2c010 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c020 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2c030 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2c040 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2c050 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2c060 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c070 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2c080 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c090 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2c0a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c0b0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2c0c0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2c0d0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2c0e0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2c0f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c100 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2c110 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2c120 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2c130 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2c140 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2c150 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2c160 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2c170 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2c180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c190 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2c1a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c1b0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2c1c0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2c1d0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2c1e0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2c1f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c200 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2c210 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2c220 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2c230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c240 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2c250 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2c260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c270 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2c280 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c290 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2c2a0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
2c2b0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2c2c0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2c2d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2c2e0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2c2f0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2c300 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2c310 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2c320 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2c330 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c340 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2c350 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
2c360 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2c370 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2c380 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2c390 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2c3a0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2c3b0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2c3c0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2c3d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2c3e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2c3f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2c400 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2c410 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2c420 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2c430 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2c440 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2c450 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2c460 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2c470 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2c480 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2c490 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2c4a0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2c4b0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2c4c0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2c4d0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2c4e0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2c4f0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2c500 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2c510 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2c520 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2c530 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
2c540 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2c550 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d  :.**.** {H13803}
2c560 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c570 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
2c580 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c590 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c5a0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2c5b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2c5c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2c5d0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2c5e0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2c5f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2c600 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68  to a BLOB and th
2c610 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
2c620 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2c630 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
2c640 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
2c650 48 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c  H13806} The [sql
2c660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c670 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  s(S,N)] interfac
2c680 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c690 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2c6a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c6b0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2c6c0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c6d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c6e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c6f0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c700 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c710 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c720 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c730 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c740 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
2c750 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2c760 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c770 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  text(S,N)]..**.*
2c780 2a 20 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b  * {H13809} The [
2c790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c7a0 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74  ytes16(S,N)] int
2c7b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2c7c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2c7d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c7e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
2c7f0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2c800 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2c810 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2c820 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2c830 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2c840 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2c850 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2c860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
2c870 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e  mn_text16(S,N)].
2c880 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20  .**.** {H13812} 
2c890 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2c8a0 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d  umn_double(S,N)]
2c8b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c8c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c8d0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2c8e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2c8f0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2c900 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2c910 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2c920 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2c930 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  nto a floating p
2c940 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a  oint value and.*
2c950 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2c960 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
2c970 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  t value..**.** {
2c980 48 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c  H13815} The [sql
2c990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2c9a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c9b0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c9c0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2c9d0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2c9e0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2c9f0 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2ca00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2ca10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ca20 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
2ca30 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2ca40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2ca50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
2ca60 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
2ca70 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2ca80 2a 20 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b  * {H13818} The [
2ca90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2caa0 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
2cab0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2cac0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2cad0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2cae0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2caf0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2cb00 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2cb10 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2cb20 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2cb30 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2cb40 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2cb50 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2cb60 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2cb70 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
2cb80 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  821} The [sqlite
2cb90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2cba0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2cbb0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2cbc0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2cbd0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2cbe0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cbf0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2cc00 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2cc10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cc20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
2cc30 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
2cc40 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2cc50 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2cc60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2cc70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2cc80 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13824} The [sqli
2cc90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cca0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
2ccb0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2ccc0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2ccd0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cce0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2ccf0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74  result set for t
2cd00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2cd10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cd20 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72  nt] S into a zer
2cd30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2cd40 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2cd50 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e  aligned UTF-16 n
2cd60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2cd70 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2cd80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2cd90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2cda0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2cdb0 7b 48 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71  {H13827} The [sq
2cdc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2cdd0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
2cde0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2cdf0 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2ce00 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2ce10 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2ce20 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2ce30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2ce40 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2ce50 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2ce60 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2ce70 20 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68           the Nth
2ce80 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2ce90 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2cea0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2ceb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2cec0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ced0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
2cee0 48 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  H13830} The [sql
2cef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2cf00 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
2cf10 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
2cf20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2cf30 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
2cf40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2cf50 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
2cf60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2cf70 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2cf80 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2cf90 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2cfa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2cfb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cfc0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73  ment] S..*/.cons
2cfd0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2cfe0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2cff0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d000 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2d010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
2d020 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d030 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2d040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d050 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2d060 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
2d070 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
2d080 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
2d090 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d0a0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d0b0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2d0c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d0d0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
2d0e0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2d0f0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2d100 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d110 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2d120 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2d130 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2d140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d150 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
2d160 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d170 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d180 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d190 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d1a0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2d1b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d1c0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
2d1d0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2d1e0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2d1f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d210 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2d220 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2d230 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20  Object {H13300} 
2d240 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e  <S70300><S30100>
2d250 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d260 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2d270 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2d280 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2d290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d2a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61  ]..** If the sta
2d2b0 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75  tement was execu
2d2c0 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
2d2d0 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
2d2e0 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a   at all, then.**
2d2f0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
2d300 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75  turned. If execu
2d310 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2d320 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
2d330 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
2d340 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
2d350 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
2d360 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d370 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
2d380 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2d390 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
2d3a0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
2d3b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d3c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
2d3d0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
2d3e0 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a  chine has not.**
2d3f0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2d400 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
2d410 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
2d420 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
2d430 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
2d440 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73  n error or an [s
2d450 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
2d460 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a   | interrupt]..*
2d470 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
2d480 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
2d490 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
2d4a0 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65  sactions cancele
2d4b0 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  d,.** depending 
2d4c0 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
2d4d0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  nces, and the.**
2d4e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65   [error code] re
2d4f0 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b  turned will be [
2d500 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
2d510 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2d520 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20  .**.** {H11302} 
2d530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  The [sqlite3_fin
2d540 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66  alize(S)] interf
2d550 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68 65  ace destroys the
2d560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d580 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73  ] S and releases
2d590 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2d5a0 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65   memory and file
2d5b0 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20   resources held 
2d5c0 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a  by that object..
2d5d0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49  **.** {H11304} I
2d5e0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2d5f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d600 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2d610 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d630 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2d640 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  an error,.**    
2d650 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2d660 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
2d670 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73 61   returns that sa
2d680 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74  me error..*/.int
2d690 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2d6a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2d6b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d6c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2d6d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2d6e0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
2d6f0 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  30} <S70300>.**.
2d700 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d710 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d720 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d730 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d740 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d750 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d760 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d770 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d780 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
2d790 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2d7a0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2d7b0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2d7c0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2d7d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2d7e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2d7f0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2d800 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2d810 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2d820 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2d830 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2d840 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2d850 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {H11332} The [s
2d860 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2d870 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2d880 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2d890 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2d8a0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
2d8b0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d8c0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d8d0 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66  *.** {H11334} If
2d8e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d8f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d900 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2d910 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2d920 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d930 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2d940 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2d950 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2d960 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
2d970 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2d980 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2d990 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2d9a0 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  n S,.**         
2d9b0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2d9c0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2d9d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2d9e0 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20  .** {H11336} If 
2d9f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2da00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2da10 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2da20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2da30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da40 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2da50 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2da60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2da70 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2da80 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2da90 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2daa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d  ..**.** {H11338}
2dab0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2dac0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2dad0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
2dae0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
2daf0 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
2db00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2db10 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2db20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2db30 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2db40 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2db50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2db60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2db70 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2db80 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2db90 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30  unctions {H16100
2dba0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
2dbb0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2dbc0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2dbd0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2dbe0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2dbf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dc00 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2dc10 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2dc20 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dc30 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2dc40 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
2dc50 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2dc60 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2dc70 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2dc80 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2dc90 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2dca0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2dcb0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2dcc0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2dcd0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2dce0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2dcf0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2dd00 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2dd10 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
2dd20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
2dd30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2dd40 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
2dd50 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
2dd60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2dd70 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
2dd80 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
2dd90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dda0 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
2ddb0 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
2ddc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ddd0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
2dde0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2ddf0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2de00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2de10 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2de20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2de30 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
2de40 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75  single program u
2de50 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2de60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2de70 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61  nnection interna
2de80 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75  lly, then SQL fu
2de90 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2dea0 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
2deb0 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61  ly to.** each da
2dec0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ded0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
2dee0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2def0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2df00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2df10 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
2df20 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68  * redefined.  Th
2df30 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2df40 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2df50 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
2df60 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
2df70 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2df80 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
2df90 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
2dfa0 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
2dfb0 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
2dfc0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
2dfd0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2dfe0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2dff0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2e000 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2e010 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20  TE_ERROR] being 
2e020 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2e030 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2e040 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2e050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2e060 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2e070 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2e080 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2e090 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
2e0a0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
2e0b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
2e0c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e0d0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2e0e0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2e0f0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2e100 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
2e110 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2e120 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2e130 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2e140 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2e150 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2e160 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2e170 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2e180 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
2e190 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2e1a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
2e1b0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2e1c0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
2e1d0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2e1e0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2e1f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e200 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2e210 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2e220 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2e230 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
2e240 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
2e250 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2e260 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2e270 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2e280 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2e290 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2e2a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2e2b0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2e2c0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2e2d0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2e2e0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
2e2f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2e300 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2e310 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2e320 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2e330 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2e340 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2e350 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2e360 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2e370 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2e380 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2e390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e3a0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2e3b0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2e3c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2e3d0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2e3e0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2e3f0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2e400 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
2e410 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2e420 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2e430 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2e440 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2e450 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2e460 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2e470 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2e480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2e490 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
2e4a0 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
2e4b0 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
2e4c0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2e4d0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2e4e0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2e4f0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2e500 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2e510 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2e520 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e530 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
2e540 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2e550 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e560 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e570 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2e580 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
2e590 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
2e5a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2e5b0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2e5c0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2e5d0 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
2e5e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2e5f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2e600 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2e610 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2e620 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
2e630 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2e640 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
2e650 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2e660 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2e670 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2e680 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2e690 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2e6a0 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2e6b0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2e6c0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2e6d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e6e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2e6f0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2e700 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2e710 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2e720 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2e730 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2e740 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2e750 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e760 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2e770 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2e780 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2e790 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2e7a0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2e7b0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2e7c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20  ion is used.  A 
2e7d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e7e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2e7f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
2e800 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
2e810 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
2e820 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2e830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e840 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
2e850 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74  e nArg.  A funct
2e860 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2e870 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2e880 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2e890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2e8a0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2e8b0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2e8c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2e8d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2e8e0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2e8f0 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  * 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 20 62 65  difference is be
2e920 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2e930 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2e940 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2e950 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e960 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e970 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2e980 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2e990 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2e9a0 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   Built-in functi
2e9b0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2e9c0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2e9d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e9e0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54   functions..** T
2e9f0 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61  he first applica
2ea00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ea10 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76  ction with a giv
2ea20 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65  en name override
2ea30 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69  s all.** built-i
2ea40 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  n functions in t
2ea50 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2ea60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69  e connection] wi
2ea70 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2ea80 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
2ea90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eaa0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66  ned functions of
2eab0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f   the same name o
2eac0 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a  nly override .**
2ead0 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69   prior applicati
2eae0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2eaf0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e  ions that are an
2eb00 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72   exact match for
2eb10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2eb20 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  f parameters and
2eb30 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64   preferred encod
2eb40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70  ing..**.** An ap
2eb50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2eb60 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2eb70 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2eb80 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2eb90 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2eba0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2ebb0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2ebc0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2ebd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2ebe0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2ebf0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2ec00 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2ec10 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2ec20 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2ec30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2ec40 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68  *.** {H16103} Th
2ec50 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ec60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
2ec70 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2ec80 20 73 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a   shall behave.**
2ec90 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
2eca0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ecb0 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ction(D,X,...)] 
2ecc0 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
2ecd0 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
2ece0 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
2ecf0 74 73 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ts the X argumen
2ed00 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  t as zero-termin
2ed10 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20  ated UTF-16.**  
2ed20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 62          native b
2ed30 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
2ed40 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72  d of as zero-ter
2ed50 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
2ed60 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20  *.** {H16106} A 
2ed70 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
2ed80 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2ed90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2eda0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2edb0 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20  n(D,X,N,E,...)] 
2edc0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2edd0 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20  register.**     
2ede0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2edf0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2ee00 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2ee10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ee20 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2ee30 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2ee40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ee50 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2ee60 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2ee70 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2ee80 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2ee90 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2eea0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39  E..**.** {H16109
2eeb0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2eec0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2eed0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2eee0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eef0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2ef00 61 6c 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20  all replace the 
2ef10 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
2ef20 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
2ef30 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
2ef40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ef50 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
2ef60 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
2ef70 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b  * {H16112} The [
2ef80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ef90 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
2efa0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2efb0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
2efc0 20 20 20 69 66 20 74 68 65 20 53 51 4c 20 66 75     if the SQL fu
2efd0 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
2efe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
2eff0 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
2f000 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
2f010 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2f020 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  tor..**.** {H161
2f030 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2f040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f050 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2f060 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
2f070 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66           shall f
2f080 61 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65  ail unless eithe
2f090 72 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  r F is NULL and 
2f0a0 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
2f0b0 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20  NULL or.***     
2f0c0 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c      F is non-NUL
2f0d0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2f0e0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
2f0f0 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2f100 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f110 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2f120 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c  rface shall fail
2f130 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2f140 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2f150 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   of [SQLITE_BUSY
2f160 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74  ] if there exist
2f170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f180 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20  ments].**       
2f190 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69     associated wi
2f1a0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2f1b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
2f1c0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54  **.** {H16124} T
2f1d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f1e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f1f0 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  N,...)] interfac
2f200 65 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74  e shall fail wit
2f210 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  h.**          an
2f220 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
2f230 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2f240 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
2f250 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
2f260 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2f270 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a  ter than 127..**
2f280 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65  .** {H16127} Whe
2f290 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  n N is non-negat
2f2a0 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ive, the [sqlite
2f2b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f2c0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2f2d0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2f2e0 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74  ace shall regist
2f2f0 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  er callbacks to 
2f300 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
2f310 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  he.**          S
2f320 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
2f330 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
2f340 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
2f350 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
2f360 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f370 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f380 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
2f390 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {H16130} When N
2f3a0 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
2f3b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f3c0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2f3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2f3e0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67  erface shall reg
2f3f0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20  ister callbacks 
2f400 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2f410 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  r the SQL.**    
2f420 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e        function n
2f430 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20  amed X with any 
2f440 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2f450 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  nts..**.** {H161
2f460 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  33} When calls t
2f470 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2f480 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f490 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f4a0 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2f4b0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f4c0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f4d0 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20  function X.**   
2f4e0 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20         and when 
2f4f0 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  one implementati
2f500 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20  on has N>=0 and 
2f510 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d  the other has N=
2f520 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  (-1).**         
2f530 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f540 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ion with a non-z
2f550 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70  ero N shall be p
2f560 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2f570 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {H16136} When ca
2f580 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2f590 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f5a0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2f5b0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2f5c0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2f5d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2f5e0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2f5f0 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2f600 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2f610 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2f620 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2f630 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2f640 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2f650 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2f660 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2f670 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2f680 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2f690 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72  ncoding shall pr
2f6a0 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eferred..**.** {
2f6b0 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61  H16139} For an a
2f6c0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f6d0 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73  ction created us
2f6e0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2f6f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f700 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f710 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66  ,P,0,S,L)] the f
2f720 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20  inalizer.**     
2f730 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20       function L 
2f740 73 68 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20  shall always be 
2f750 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20  invoked exactly 
2f760 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20  once if the.**  
2f770 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e          step fun
2f780 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65  ction S is calle
2f790 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
2f7a0 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  mes..**.** {H161
2f7b0 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20  42} When SQLite 
2f7c0 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74  invokes either t
2f7d0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65  he xFunc or xSte
2f7e0 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a  p function of.**
2f7f0 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70            an app
2f800 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f820 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74   aggregate creat
2f830 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
2f840 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  y [sqlite3_creat
2f850 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72  e_function()] or
2f860 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f870 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a  _function16()],.
2f880 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2f890 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73   the array of [s
2f8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f8b0 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20  jects passed as 
2f8c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f8d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f8e0 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63  shall be [protec
2f8f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f900 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
2f910 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2f920 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
2f930 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2f940 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2f950 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2f960 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2f970 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2f980 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2f990 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f9a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2f9b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2f9c0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2f9d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2f9e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2f9f0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2fa00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fa10 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2fa20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fa30 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
2fa40 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
2fa50 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2fa60 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2fa70 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2fa80 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2fa90 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2faa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fac0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2fad0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fae0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2faf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fb00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2fb10 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
2fb20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fb30 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
2fb40 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e  H10267} <S50200>
2fb50 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H16100>.**.** 
2fb60 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
2fb70 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
2fb80 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
2fb90 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
2fba0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
2fbb0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
2fbc0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
2fbd0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
2fbe0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2fbf0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
2fc00 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2fc10 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
2fc20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2fc30 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
2fc40 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
2fc50 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
2fc60 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
2fc70 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
2fc80 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
2fc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fca0 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
2fcb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2fcc0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
2fcd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2fce0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
2fcf0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
2fd00 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
2fd10 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
2fd20 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
2fd30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2fd40 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
2fd50 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2fd60 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2fd70 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2fd80 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2fd90 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
2fda0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
2fdb0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2fdc0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
2fdd0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2fde0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2fdf0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2fe00 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2fe10 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2fe20 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2fe30 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2fe40 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2fe50 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2fe60 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
2fe70 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
2fe80 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
2fe90 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
2fea0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2feb0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2fec0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fed0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2fee0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2fef0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
2ff00 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2ff10 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2ff20 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2ff30 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2ff40 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2ff50 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
2ff60 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2ff70 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
2ff80 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
2ff90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
2ffa0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
2ffb0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
2ffc0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2ffd0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
2ffe0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2fff0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
30000 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
30010 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
30020 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
30030 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
30040 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
30050 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
30060 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30  es {H15100} <S20
30070 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  200>.**.** The C
30080 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
30090 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
300a0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
300b0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
300c0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
300d0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
300e0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
300f0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
30100 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
30110 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
30120 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
30130 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
30140 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
30150 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
30160 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
30170 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
30180 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
30190 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
301a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
301b0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
301c0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
301d0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
301e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
301f0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
30200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30210 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
30220 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
30230 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
30240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30250 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
30260 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
30270 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30280 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
30290 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
302a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
302b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
302c0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
302d0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
302e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
302f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
30300 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30310 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
30320 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
30330 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30340 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
30350 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
30360 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
30370 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30380 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
30390 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
303a0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
303b0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
303c0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
303d0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
303e0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
303f0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30400 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
30410 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
30420 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
30430 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
30440 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30450 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
30460 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
30470 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
30480 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
30490 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
304a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
304b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
304c0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
304d0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
304e0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
304f0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
30500 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
30510 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
30520 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30530 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
30540 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30550 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
30560 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
30570 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
30580 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
30590 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
305a0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
305b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
305c0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
305d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
305e0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
305f0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
30600 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
30610 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
30620 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
30630 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
30640 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
30650 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
30660 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
30670 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
30680 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
30690 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
306a0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
306b0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
306c0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
306d0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
306e0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
306f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
30700 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
30710 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
30720 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
30730 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
30740 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
30750 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
30760 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
30770 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
30780 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
30790 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
307a0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
307b0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
307c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
307d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
307e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
307f0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
30800 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30810 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
30820 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
30830 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
30840 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
30850 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
30860 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30870 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
30880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30890 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
308a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
308b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
308c0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
308d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
308e0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
308f0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
30900 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
30910 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
30920 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
30930 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  rs..**.** INVARI
30940 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ANTS:.**.** {H15
30950 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
30960 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
30970 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30980 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30990 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
309a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
309b0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c  ject V into a BL
309c0 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20  OB and then.**  
309d0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
309e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
309f0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
30a00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d  ..**.** {H15106}
30a10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30a20 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
30a30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30a40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30a50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
30a60 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
30a70 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
30a80 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
30a90 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
30aa0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
30ab0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
30ac0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
30ad0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
30ae0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30af0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30b00 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
30b10 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
30b20 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
30b30 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b  * {H15109} The [
30b40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30b50 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
30b60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
30b70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
30b80 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
30b90 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
30ba0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
30bb0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
30bc0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
30bd0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
30be0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
30bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
30c00 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30c10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30c20 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
30c30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
30c40 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
30c50 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
30c60 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
30c70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  )]..**.** {H1511
30c80 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30c90 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
30ca0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30cb0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30cc0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ce0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
30cf0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
30d00 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
30d10 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
30d20 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
30d30 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20  .**.** {H15115} 
30d40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30d50 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
30d60 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
30d70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
30d80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30d90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
30da0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
30db0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
30dc0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
30dd0 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
30de0 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
30df0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
30e00 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  H15118} The [sql
30e10 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
30e20 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
30e30 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
30e40 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
30e50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30e60 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
30e70 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
30e80 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
30e90 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
30ea0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
30eb0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
30ec0 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
30ed0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
30ee0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30ef0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
30f00 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
30f10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30f20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
30f30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
30f40 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
30f50 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
30f60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
30f70 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
30f80 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68  *.** {H15124} Th
30f90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30fa0 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
30fb0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30fc0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30fd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30fe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30ff0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
31000 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
31010 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
31020 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
31030 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
31040 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
31050 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31060 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31070 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31080 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
31090 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
310a0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
310b0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
310c0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
310d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
310e0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
310f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31100 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
31110 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
31120 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
31130 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
31140 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
31150 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
31160 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
31170 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
31180 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31190 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
311a0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
311b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
311c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
311d0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
311e0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
311f0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
31200 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
31210 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
31220 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
31230 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
31240 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31250 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
31260 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20  ** {H15133} The 
31270 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31280 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
31290 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
312a0 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
312b0 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
312c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
312d0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
312e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
312f0 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
31300 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
31310 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
31320 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
31330 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31340 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
31350 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
31360 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
31370 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
31380 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
31390 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
313a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
313b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
313c0 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
313d0 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
313e0 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
313f0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
31400 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
31410 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
31420 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
31430 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
31440 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
31450 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
31460 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
31470 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
31480 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
31490 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
314a0 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
314b0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
314c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
314d0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
314e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
314f0 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
31500 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
31510 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
31520 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31530 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
31540 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
31550 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31560 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31580 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
31590 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
315a0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
315b0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
315c0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
315d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
315e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
315f0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
31600 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
31610 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
31620 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
31630 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
31640 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
31650 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31660 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31670 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31690 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
316a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
316b0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
316c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
316d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
316e0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
316f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31700 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
31710 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
31720 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
31730 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
31740 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
31750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31760 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
31770 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
31780 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32  t {H16210} <S202
31790 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d  00>.**.** The im
317a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
317b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
317c0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
317d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
317e0 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74  cate.** a struct
317f0 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ure for storing 
31800 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
31810 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
31820 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
31830 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31840 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
31850 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72  led for a.** par
31860 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
31870 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61  e, SQLite alloca
31880 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65  tes nBytes of me
31890 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
318a0 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   that.** memory,
318b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
318c0 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e  ointer to it. On
318d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
318e0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
318f0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
31900 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
31910 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
31920 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
31930 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ndex,.** the sam
31940 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
31950 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d  rned. The implem
31960 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31970 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
31980 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65  e.** the returne
31990 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
319a0 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
319b0 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  ** SQLite automa
319c0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
319d0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66  e allocated buff
319e0 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  er when the aggr
319f0 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63  egate.** query c
31a00 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31a10 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31a20 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
31a30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
31a40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
31a50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
31a60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
31a70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
31a80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
31a90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
31aa0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
31ab0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
31ac0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
31ad0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
31ae0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
31af0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
31b00 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
31b10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31b20 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
31b30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
31b40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31  S:.**.** {H16211
31b50 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
31b60 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
31b70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31b80 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
31b90 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
31ba0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
31bb0 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
31bc0 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
31bd0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
31be0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
31bf0 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
31c00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62   to allocate N b
31c10 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a  ytes of memory,.
31c20 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
31c30 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
31c40 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
31c50 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61  er to the alloca
31c60 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  ted memory..**.*
31c70 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20  * {H16213} If a 
31c80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31c90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
31ca0 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  uring.**        
31cb0 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
31cc0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31cd0 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
31ce0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a  tion returns 0..
31cf0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53  **.** {H16215} S
31d00 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31d10 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
31d20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
31d30 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
31d40 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
31d50 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f   for the same co
31d60 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a  ntext pointer C.
31d70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f  **          igno
31d80 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  re the N paramet
31d90 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  er and return a 
31da0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
31db0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
31dc0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
31dd0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
31de0 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
31df0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d  ..**.** {H16217}
31e00 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
31e10 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  cated by [sqlite
31e20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31e30 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20  ext(C,N)] is.** 
31e40 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74           automat
31e50 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20  ically freed on 
31e60 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
31e70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31e80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
31e90 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
31ea0 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b  ize()] for the [
31eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31ec0 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  nt] containing.*
31ed0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
31ee0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31ef0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
31f00 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a  h context C..*/.
31f10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
31f20 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31f30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31f40 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
31f50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31f60 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
31f70 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d  nctions {H16240}
31f80 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
31f90 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
31fa0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
31fb0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
31fc0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
31fd0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
31fe0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
31ff0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
32000 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32010 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32020 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32030 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32040 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32050 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
32060 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
32070 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
32080 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
32090 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
320a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
320b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
320c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
320d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
320e0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
320f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32100 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32110 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
32120 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34  TS:.**.** {H1624
32130 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
32140 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e  user_data(C)] in
32150 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32160 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
32170 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e            P poin
32180 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
32190 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
321a0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
321b0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
321c0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
321d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
321e0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
321f0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
32200 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
32210 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
32220 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
32230 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
32240 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f  ontext] C..*/.vo
32250 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
32260 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
32270 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
32280 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
32290 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
322a0 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
322b0 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
322c0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
322d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
322e0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
322f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32300 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
32310 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
32320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32330 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
32340 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32350 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32360 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32370 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32380 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32390 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
323a0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
323b0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
323c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
323d0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
323e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
323f0 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65  .** {H16253} The
32400 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32410 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20  t_db_handle(C)] 
32420 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32430 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
32440 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f  **          D po
32450 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
32460 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32470 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
32480 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
32490 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
324a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
324b0 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
324c0 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
324d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
324e0 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
324f0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
32500 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
32510 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
32520 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
32530 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
32540 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32550 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
32560 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
32570 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b  Auxiliary Data {
32580 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e  H16270} <S20200>
32590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
325a0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
325b0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
325c0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
325d0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
325e0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
325f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
32600 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
32610 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
32620 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
32630 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
32640 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
32650 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
32660 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
32670 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
32680 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
32690 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
326a0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
326b0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
326c0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
326d0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
326e0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
326f0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
32700 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
32710 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
32720 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
32730 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
32740 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
32750 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32760 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
32770 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
32780 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
32790 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
327a0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
327b0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
327c0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
327d0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
327e0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
327f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
32800 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
32810 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
32820 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
32830 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
32840 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
32850 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
32860 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
32870 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32880 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
32890 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
328a0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
328b0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
328c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
328d0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
328e0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
328f0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
32900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32910 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49  ined function. I
32920 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
32930 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
32940 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
32950 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
32960 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
32970 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
32980 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
32990 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
329a0 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
329b0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
329c0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
329d0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
329e0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
329f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
32a00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
32a10 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32a20 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
32a30 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
32a40 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
32a50 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
32a60 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
32a70 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
32a80 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
32a90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32aa0 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
32ab0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
32ac0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32ad0 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
32ae0 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
32af0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
32b00 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
32b10 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
32b20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
32b30 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
32b40 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
32b50 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
32b60 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32b70 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
32b80 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
32b90 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
32ba0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32bb0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
32bc0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
32bd0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
32be0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
32bf0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
32c00 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
32c10 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
32c20 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
32c30 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
32c40 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
32c50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
32c60 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
32c70 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20   any time.  The 
32c80 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
32c90 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
32ca0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
32cb0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
32cc0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
32cd0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
32ce0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
32cf0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
32d00 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
32d10 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
32d20 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
32d30 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
32d40 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
32d50 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
32d60 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
32d70 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
32d80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32d90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
32da0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32db0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32dc0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
32dd0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32de0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
32df0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
32e00 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  72} The [sqlite3
32e10 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
32e20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
32e30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
32e40 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65  *          to me
32e50 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32e60 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70  d with the Nth p
32e70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
32e80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
32e90 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63           whose c
32ea0 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20  ontext is C, or 
32eb0 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
32ec0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   no metadata ass
32ed0 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
32ee0 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61      with that pa
32ef0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
32f00 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c  H16274} The [sql
32f10 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32f20 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72  (C,N,P,D)] inter
32f30 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d  face assigns a m
32f40 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
32f50 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f      pointer P to
32f60 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
32f70 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
32f80 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74  nction with cont
32f90 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ext C..**.** {H1
32fa0 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c  6276} SQLite wil
32fb0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
32fc0 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
32fd0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
32fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
32ff0 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61  ch is the metada
33000 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c  ta pointer P fol
33010 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
33020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33030 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33040 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e  a(C,N,P,D)] when
33050 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
33060 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20  o hold.**       
33070 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e     the metadata.
33080 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20  .**.** {H16277} 
33090 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
330a0 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66   hold metadata f
330b0 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  or an SQL functi
330c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
330d0 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68           when th
330e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
330f0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
33100 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38  s..**.** {H16278
33110 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
33120 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
33130 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  P,D)] is invoked
33140 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  , the destructor
33150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33160 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70  called for any p
33170 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73  rior metadata as
33180 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33190 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
331a0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
331b0 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65  ext C and parame
331c0 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ter N..**.** {H1
331d0 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  6279} SQLite wil
331e0 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f  l call destructo
331f0 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64  rs for any metad
33200 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e  ata it is holdin
33210 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
33220 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70   a particular [p
33230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33240 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72  t] S when either
33250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33260 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33270 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
33280 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
33290 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
332a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
332b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
332c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
332d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
332e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
332f0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
33300 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
33310 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
33320 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
33330 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
33340 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
33350 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
33360 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
33370 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
33380 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
33390 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
333a0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
333b0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
333c0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
333d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
333e0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
333f0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
33400 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
33410 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
33420 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
33430 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
33440 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
33450 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
33460 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
33470 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
33480 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
33490 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
334a0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
334b0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
334c0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
334d0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
334e0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
334f0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
33500 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
33510 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
33520 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
33530 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
33540 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
33550 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
33560 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
33570 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
33580 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
33590 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
335a0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
335b0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
335c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
335d0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
335e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
335f0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33600 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33610 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33620 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33630 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33640 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33650 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33660 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33670 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33680 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
33690 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
336a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
336b0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
336c0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
336d0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
336e0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
336f0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33700 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
33710 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33720 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
33730 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33740 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
33750 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33760 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
33770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
33780 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
33790 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
337a0 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
337b0 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
337c0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
337d0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
337e0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
337f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
33800 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
33810 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
33820 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
33830 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
33840 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
33850 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33860 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
33870 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33880 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
33890 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
338a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
338b0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
338c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
338d0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
338e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
338f0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
33900 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
33910 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
33920 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
33930 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33940 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33950 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33960 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
33970 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33980 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33990 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
339a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
339b0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
339c0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
339d0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
339e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
339f0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
33a00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33a10 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
33a20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33a30 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
33a40 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
33a50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33a60 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
33a70 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
33a80 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
33a90 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
33aa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33ab0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33ac0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
33ad0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
33ae0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
33af0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
33b00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
33b10 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
33b20 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
33b30 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
33b40 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33b50 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
33b60 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
33b70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
33b80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33b90 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
33ba0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
33bb0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
33bc0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
33bd0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33be0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
33bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c00 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
33c10 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
33c20 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
33c30 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
33c40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33c50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
33c60 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
33c70 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
33c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33c90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33ca0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33cb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33cc0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
33cd0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
33ce0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
33cf0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
33d00 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
33d10 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
33d20 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
33d30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
33d40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
33d50 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
33d60 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
33d70 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
33d80 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
33d90 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
33da0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
33db0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
33dc0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
33dd0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
33de0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
33df0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33e00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
33e10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33e20 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
33e30 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
33e40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
33e50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
33e60 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
33e70 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
33e80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
33e90 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
33ea0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
33eb0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
33ec0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
33ed0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
33ee0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33ef0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
33f00 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
33f10 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
33f20 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
33f30 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
33f40 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
33f50 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
33f60 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
33f70 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
33f80 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
33f90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
33fa0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
33fb0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
33fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33fd0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
33fe0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
33ff0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
34000 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34010 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
34020 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
34030 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
34040 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
34050 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
34060 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
34070 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
34080 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
34090 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
340a0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
340b0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
340c0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
340d0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
340e0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
340f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
34100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
34110 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
34120 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34130 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34140 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34150 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34160 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34170 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
34180 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34190 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
341a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
341b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
341c0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
341d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
341e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
341f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34200 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34210 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
34220 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
34230 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
34240 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
34250 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
34260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
34270 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
34280 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34290 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
342a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
342b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
342c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
342d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
342e0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
342f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
34300 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
34310 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
34320 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34330 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
34340 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
34350 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34360 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34370 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34380 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
34390 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
343a0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
343b0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
343c0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
343d0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
343e0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
343f0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
34400 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
34410 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
34420 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
34430 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
34440 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
34450 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34460 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
34470 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34480 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
34490 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
344a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
344b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
344c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
344d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
344e0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
344f0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34500 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34510 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34520 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34530 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
34540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34560 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34570 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
34580 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
34590 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
345a0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
345b0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
345c0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
345d0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
345e0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
345f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
34600 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
34610 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
34620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34640 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34650 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34660 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
34670 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
34680 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
34690 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
346a0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
346b0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
346c0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
346d0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
346e0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
346f0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
34700 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
34710 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34720 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34730 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
34740 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34750 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34760 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34770 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
34780 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
34790 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
347a0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
347b0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
347c0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
347d0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
347e0 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
347f0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
34800 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
34810 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
34820 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
34830 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34840 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34850 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34860 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34870 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
34880 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
34890 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
348a0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
348b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
348c0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
348d0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
348e0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
348f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
34900 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
34910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34920 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34930 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34940 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
34950 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
34960 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34970 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
34980 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
34990 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
349a0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
349b0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
349c0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
349d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
349e0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
349f0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
34a00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34a10 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
34a20 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
34a30 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
34a40 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
34a50 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
34a60 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
34a70 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
34a80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
34a90 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
34aa0 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
34ab0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34ac0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
34ad0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
34ae0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
34af0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34b00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
34b10 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
34b20 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
34b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34b40 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
34b50 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
34b60 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
34b70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34b80 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
34b90 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
34ba0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
34bb0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
34bc0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
34bd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34be0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
34bf0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
34c00 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
34c10 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
34c20 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
34c30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34c40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33  S:.**.** {H16403
34c50 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65  } The default re
34c60 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
34c70 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  any SQL function
34c80 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
34c90 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71  {H16406} The [sq
34ca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34cb0 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  b(C,V,N,D)] inte
34cc0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34cd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34ce0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34cf0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
34d00 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20   BLOB that is N 
34d10 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
34d20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20    in length and 
34d30 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69  with content poi
34d40 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a  nted to by V..**
34d50 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65  .** {H16409} The
34d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34d70 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e  _double(C,V)] in
34d80 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
34d90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34da0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34db0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
34dc0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
34dd0 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  int value V..**.
34de0 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20  ** {H16412} The 
34df0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34e00 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e  error(C,V,N)] in
34e10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
34e20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
34e30 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
34e40 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
34e50 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
34e60 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
34e70 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
34e80 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
34e90 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61  TF-8 error messa
34ea0 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56  ge copied from V
34eb0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20   up to the.**   
34ec0 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72         first zer
34ed0 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20  o byte or until 
34ee0 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
34ef0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
34f00 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35  e..**.** {H16415
34f10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34f20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c  esult_error16(C,
34f30 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
34f40 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
34f50 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
34f60 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
34f70 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
34f80 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
34f90 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
34fa0 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
34fb0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61   and a UTF-16 na
34fc0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
34fd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
34fe0 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
34ff0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
35000 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
35010 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
35020 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
35030 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
35040 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
35050 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54  **.** {H16418} T
35060 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35070 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
35080 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
35090 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
350a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
350b0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
350c0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
350d0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
350e0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
350f0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
35100 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
35110 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
35120 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
35130 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
35140 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
35150 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
35160 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
35170 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
35180 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
35190 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
351a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
351b0 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
351c0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
351d0 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
351e0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
351f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
35200 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {H16424} The [sq
35210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35220 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
35230 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
35240 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
35250 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
35260 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
35270 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
35280 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
35290 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
352a0 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
352b0 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
352c0 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nged..**.** {H16
352d0 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
352e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
352f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
35300 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
35310 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
35320 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
35330 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
35340 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
35350 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d  ..**.** {H16430}
35360 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35370 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
35380 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
35390 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
353a0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
353b0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
353c0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
353d0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
353e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54  **.** {H16433} T
353f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35400 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
35410 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
35420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
35430 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
35440 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
35450 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
35460 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
35470 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
35480 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
35490 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
354a0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
354b0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
354c0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
354d0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  F-8 string.**   
354e0 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
354f0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
35500 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
35510 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
35520 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
35530 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
35540 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
35550 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {H16439} The [s
35560 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35570 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
35580 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35590 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
355a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
355b0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
355c0 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74  e the UTF-16 nat
355d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
355e0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
355f0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
35600 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
35610 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
35620 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
35630 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
35640 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
35650 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
35660 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  442} The [sqlite
35670 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
35680 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
35690 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
356a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
356b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
356c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
356d0 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  he UTF-16 big-en
356e0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
356f0 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
35700 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
35710 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
35720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
35730 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
35740 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
35750 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
35760 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b  * {H16445} The [
35770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35780 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
35790 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
357a0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
357b0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
357c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
357d0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
357e0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
357f0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
35800 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
35810 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
35820 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
35830 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
35840 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
35850 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
35860 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
35870 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
35880 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
35890 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
358a0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
358b0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
358c0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
358d0 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72   to be the [unpr
358e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
358f0 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
35900 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
35910 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20  ** {H16451} The 
35920 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35930 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
35940 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35950 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35960 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35970 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35980 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42  e an N-byte BLOB
35990 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
359a0 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68  *.** {H16454} Th
359b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
359c0 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
359d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
359e0 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
359f0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
35a00 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
35a10 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
35a20 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
35a30 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
35a40 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
35a50 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {H16457} If the 
35a60 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
35a70 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
35a80 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
35a90 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
35aa0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35ab0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
35ac0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
35ad0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
35ae0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35af0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35b00 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
35b10 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
35b20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35b30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
35b40 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
35b50 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
35b60 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
35b70 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
35b80 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
35b90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
35ba0 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
35bb0 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
35bc0 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
35bd0 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
35be0 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74  ** {H16460} If t
35bf0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
35c00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35c10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35c20 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
35c30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35c40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
35c50 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
35c60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35c70 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35c80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35c90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35ca0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
35cb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35cc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35cd0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
35ce0 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
35cf0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
35d00 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
35d10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
35d20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35d30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35d40 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
35d50 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
35d60 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33  y..**.** {H16463
35d70 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
35d80 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
35d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
35da0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
35db0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35dc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35dd0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
35de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35df0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
35e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35e20 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
35e30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35e50 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
35e60 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
35e70 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
35e80 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
35e90 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
35ea0 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
35eb0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
35ec0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
35ed0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
35ee0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35ef0 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
35f00 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
35f10 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
35f20 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
35f30 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
35f40 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
35f50 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
35f60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35f70 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35f80 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
35f90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35fa0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
35fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
35fc0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
35fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35fe0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
35ff0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36000 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36010 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36020 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36030 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36040 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
36050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36060 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
36070 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36090 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
360a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
360b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
360c0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
360d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
360e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
360f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
36100 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36110 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36120 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
36130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36140 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
36150 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36160 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
36170 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
36180 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36190 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
361a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
361b0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
361c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
361d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
361e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
361f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36200 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
36210 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36220 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36230 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
36240 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36250 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
36260 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36270 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36280 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
36290 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
362a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
362b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
362c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
362d0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
362e0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
362f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
36300 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
36310 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
36320 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
36330 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36340 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
36350 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
36360 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
36370 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
36380 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
36390 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
363a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
363b0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
363c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
363d0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
363e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
363f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
36400 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
36410 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
36420 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
36430 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
36440 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
36450 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36460 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
36470 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36480 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
36490 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
364a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
364b0 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
364c0 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
364d0 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
364e0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
364f0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
36500 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
36510 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
36520 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
36530 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
36540 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
36550 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
36560 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
36570 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
36580 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
36590 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
365a0 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
365b0 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
365c0 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
365d0 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
365e0 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c  6 little-endian,
365f0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
36600 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
36610 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
36620 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
36630 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
36640 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36650 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
36660 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
36670 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
36680 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
36690 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
366a0 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
366b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
366c0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
366d0 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
366e0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
366f0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
36700 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
36710 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
36720 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
36730 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
36740 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
36750 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
36760 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
36770 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
36780 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
36790 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
367a0 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
367b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
367c0 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
367d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
367e0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
367f0 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
36800 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
36810 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
36820 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
36830 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
36840 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36850 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
36860 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36870 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
36880 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
36890 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
368a0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
368b0 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
368c0 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
368d0 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
368e0 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
368f0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
36900 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
36910 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
36920 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
36930 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
36940 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
36950 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
36960 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
36970 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
36980 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
36990 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
369a0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
369b0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
369c0 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
369d0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
369e0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
369f0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
36a00 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
36a10 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
36a20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
36a30 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
36a40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36a50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
36a60 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
36a70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36a80 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
36a90 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
36aa0 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
36ab0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
36ac0 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
36ad0 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
36ae0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
36af0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
36b00 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
36b10 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
36b20 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
36b30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
36b40 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
36b50 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
36b60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36b70 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
36b80 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
36b90 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
36ba0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
36bb0 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
36bc0 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
36bd0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
36be0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
36bf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36c00 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
36c10 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
36c20 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
36c30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36c40 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20  *.** {H16603} A 
36c50 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
36c60 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
36c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
36c80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36c90 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
36ca0 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
36cb0 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
36cc0 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
36cd0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
36ce0 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
36cf0 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
36d00 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
36d10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36d20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
36d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
36d40 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
36d50 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
36d60 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {H16604} SQLite 
36d70 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
36d80 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
36d90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
36da0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36db0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
36dc0 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
36dd0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
36de0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
36df0 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
36e00 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
36e10 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
36e20 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
36e30 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
36e40 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
36e50 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
36e60 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 73   {H16606} Succes
36e70 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
36e80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36e90 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36ea0 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
36eb0 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
36ec0 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
36ed0 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
36ee0 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
36ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
36f00 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
36f10 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74  ** {H16609} If t
36f20 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
36f30 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
36f40 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36f50 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
36f60 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
36f70 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
36f80 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
36f90 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
36fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
36fb0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36fc0 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
36fd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  Lite..**.** {H16
36fe0 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
36ff0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
37000 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
37010 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
37020 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {H16615} A col
37030 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37040 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
37050 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37060 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
37070 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
37080 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
37090 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  se()]..**.** {H1
370a0 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
370b0 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
370c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
370d0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
370e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
370f0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
37100 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
37110 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
37120 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
37130 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
37140 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
37150 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
37160 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  f F..**.** {H166
37170 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
37180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37190 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
371a0 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
371b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
371c0 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
371d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
371e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
371f0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
37200 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
37210 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
37220 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
37230 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {H16624} Foll
37240 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
37250 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37260 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
37270 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
37280 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
37290 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
372a0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
372b0 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
372c0 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
372d0 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  ions on the [dat
372e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
372f0 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
37300 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
37310 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
37320 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
37330 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48  amed X..**.** {H
37340 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
37350 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37360 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
37370 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
37380 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
37390 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
373a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
373b0 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
373c0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
373d0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
373e0 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
373f0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
37400 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
37420 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
37430 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68  *.** {H16630} Wh
37440 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
37450 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
37460 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
37470 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
37480 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
37490 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
374a0 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
374b0 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
374c0 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
374d0 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
374e0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
374f0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
37500 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
37510 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
37520 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
37530 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
37540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37550 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
37560 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
37570 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
37580 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
37590 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
375a0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
375b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
375c0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
375d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
375e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
375f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37600 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37610 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37620 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
37630 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37640 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37650 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37660 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
37670 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
37680 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37690 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
376a0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
376b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
376c0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
376d0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
376e0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
376f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37700 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37710 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37720 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
37730 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
37740 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
37750 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
37760 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
37770 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
37780 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37790 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
377a0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
377b0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
377c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
377d0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
377e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
377f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37800 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
37810 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
37820 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
37830 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
37840 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
37850 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37860 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37870 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
37880 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37890 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
378a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
378b0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
378c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
378d0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
378e0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
378f0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
37900 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
37910 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
37920 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
37930 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
37940 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
37950 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
37960 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
37970 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
37980 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
37990 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
379a0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
379b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
379c0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
379d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
379e0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
379f0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
37a00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
37a10 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37a20 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
37a30 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37a40 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
37a50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
37a60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
37a70 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
37a80 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
37a90 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
37aa0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
37ab0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
37ac0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
37ad0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
37ae0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
37af0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
37b00 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37b10 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
37b20 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
37b30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
37b40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37b50 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
37b60 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
37b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
37b80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
37b90 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
37ba0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
37bb0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
37bc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37bd0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
37be0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37bf0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
37c00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37c10 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
37c20 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
37c30 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32  S:.**.** {H16702
37c40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
37c50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37c60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37c70 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
37c80 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
37c90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37ca0 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
37cb0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
37cc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37cd0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
37ce0 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
37cf0 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
37d00 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
37d10 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
37d20 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
37d30 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
37d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
37d50 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
37d60 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
37d70 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
37d80 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68  ** {H16704} Each
37d90 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37da0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
37db0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
37dc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
37dd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37de0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
37df0 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
37e00 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
37e10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
37e20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
37e40 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
37e50 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
37e60 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
37e70 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68  *.** {H16706} Th
37e80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
37e90 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
37ea0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
37eb0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
37ec0 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
37ed0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
37ee0 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
37ef0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
37f00 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
37f10 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37f20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37f30 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
37f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37f50 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
37f60 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
37f70 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
37f80 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
37f90 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
37fa0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37fb0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
37fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
37fd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
37fe0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37ff0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
38000 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
38010 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
38020 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
38030 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38040 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
38050 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
38060 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
38070 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
38080 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
38090 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
380a0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
380b0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
380c0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
380d0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
380e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
380f0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
38100 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
38110 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
38120 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
38130 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
38140 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
38150 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
38160 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38170 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
38180 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
38190 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
381a0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
381b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
381c0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
381d0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
381e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
381f0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
38200 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
38210 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
38220 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
38230 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
38240 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
38250 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
38260 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
38270 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
38280 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
38290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
382a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
382b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
382c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
382d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
382e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
382f0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
38300 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
38310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38320 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
38330 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
38340 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
38350 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
38360 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
38370 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
38380 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
38390 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
383a0 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
383b0 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
383c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
383d0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
383e0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
383f0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
38400 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
38410 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
38420 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
38430 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
38440 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
38450 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
38460 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
38470 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
38480 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
38490 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
384a0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
384b0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
384c0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
384d0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
384e0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
384f0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
38500 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
38510 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
38520 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
38530 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
38540 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
38550 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
38560 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
38570 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
38580 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
38590 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
385a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
385b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
385c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
385d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d  :.**.** {H10533}
385e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
385f0 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
38600 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
38610 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
38620 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
38630 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
38640 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
38650 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
38660 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
38670 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
38680 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
38690 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
386a0 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
386b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d  ..**.** {H10536}
386c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
386d0 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
386e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
386f0 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
38700 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
38710 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
38720 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
38730 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
38740 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
38750 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
38760 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
38770 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
38780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
38790 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
387a0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
387b0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
387c0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
387d0 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53  iles {H10310} <S
387e0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  20000>.**.** If 
387f0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
38800 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
38810 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
38820 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
38830 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
38840 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
38850 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
38860 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
38870 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
38880 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61  Lite will be pla
38890 63