/ Hex Artifact Content
Login

Artifact 8fef8cb666774774dc66e5efaa9ddbdd582b3e74:


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 39 20 32 30 30 38 2f 31  n,v 1.419 2008/1
05f0: 32 2f 31 35 20 32 32 3a 35 31 3a 33 39 20 64 72  2/15 22:51:39 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 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69  e [ROWID | "rowi
fd80: 64 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69  d"]. The rowid i
fd90: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
fda0: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
fdb0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
fdc0: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
fdd0: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
fde0: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
fdf0: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
fe00: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
fe10: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
fe20: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
fe30: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
fe40: 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
fe50: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
fe60: 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
fe70: 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
fe80: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
fe90: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
fea0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
feb0: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
fec0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
fed0: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
fee0: 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
fef0: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
ff00: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ff10: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
ff20: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ff30: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
ff40: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
ff50: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
ff60: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
ff70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
ff80: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
ff90: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b  d..**.** If an [
ffa0: 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
ffb0: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
ffc0: 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64   then the [rowid
ffd0: 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
ffe0: 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
fff0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
10000 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
10010 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
10020 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
10030 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
10040 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
10050 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10060 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
10070 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
10080 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
10090 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
100a0 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a  trigger fired..*
100b0 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d  *.** An [INSERT]
100c0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
100d0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
100e0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
100f0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
10100 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
10110 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
10120 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10130 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
10140 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
10150 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
10160 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
10170 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
10180 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
10190 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
101a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
101b0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
101c0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
101d0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
101e0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
101f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10200 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
10210 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10220 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
10230 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
10240 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
10250 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
10260 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
10270 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
10280 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
10290 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
102a0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
102b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
102c0 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
102d0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
102e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
102f0 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
10300 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
10310 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
10320 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
10330 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
10340 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
10350 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
10360 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
10370 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
10380 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73   {H12221} The [s
10390 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
103a0 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
103b0 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
103c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
103d0 65 20 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20  e [rowid].**    
103e0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73        of the mos
103f0 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
10400 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72  ful [INSERT] per
10410 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
10420 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
10430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10440 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
10450 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
10460 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
10470 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
10480 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
10490 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
104a0 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a   no qualifying.*
104b0 2a 20 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45  *          [INSE
104c0 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  RT] statements..
104d0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54  **.** {H12223} T
104e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
104f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10500 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
10510 72 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20  return the.**   
10520 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75         same valu
10530 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  e when called fr
10540 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  om the same trig
10550 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ger context.**  
10560 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74          immediat
10570 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61  ely before and a
10580 66 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  fter a [ROLLBACK
10590 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  ]..**.** ASSUMPT
105a0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
105b0 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  232} If a separa
105c0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
105d0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
105e0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
105f0 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
10600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
10610 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
10620 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
10630 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  id()].**        
10640 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75    function is ru
10650 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
10660 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
10670 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
10680 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
10690 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
106a0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
106b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
106c0 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  d()] is.**      
106d0 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c      unpredictabl
106e0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
106f0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
10700 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
10710 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74  **          last
10720 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
10730 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
10740 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
10750 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
10760 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
10770 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
10780 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
10790 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34   Modified {H1224
107a0 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S10600>.**.*
107b0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
107c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
107d0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72  er of database r
107e0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68  ows that were ch
107f0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65  anged.** or inse
10800 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20  rted or deleted 
10810 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
10820 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53  ntly completed S
10830 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
10840 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
10850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
10860 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  cified by the fi
10870 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
10880 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  * Only changes t
10890 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
108a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
108b0 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
108c0 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
108d0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
108e0 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
108f0 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
10900 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
10910 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75  gers are not cou
10920 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  nted. Use the [s
10930 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
10940 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
10950 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
10960 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
10970 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
10980 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
10990 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
109a0 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67  .** A "row chang
109b0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
109c0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
109d0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
109e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
109f0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
10a00 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
10a10 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
10a20 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
10a30 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
10a40 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
10a50 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
10a60 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
10a70 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
10a80 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20   DROP TABLE, or 
10a90 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
10aa0 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
10ab0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
10ac0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  t row changes..*
10ad0 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
10ae0 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
10af0 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
10b00 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
10b10 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
10b20 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72  e script of a tr
10b30 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c  igger.  Most SQL
10b40 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
10b50 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
10b60 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
10b70 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
10b80 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
10b90 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10ba0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
10bb0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
10bc0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
10bd0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
10be0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
10bf0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
10c00 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
10c10 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
10c20 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
10c30 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
10c40 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
10c50 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
10c60 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
10c70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
10c80 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
10c90 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
10ca0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
10cb0 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  xt..**.** This f
10cc0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
10cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
10ce0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
10cf0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
10d00 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
10d10 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
10d20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
10d30 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
10d40 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
10d50 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20  *.** Thus, when 
10d60 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
10d70 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
10d80 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
10d90 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
10da0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
10db0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
10dc0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10dd0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
10de0 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
10df0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
10e00 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
10e10 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
10e20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
10e30 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
10e40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
10e50 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
10e60 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
10e70 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
10e80 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
10e90 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
10ea0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
10eb0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
10ec0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
10ed0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
10ee0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
10ef0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
10f00 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
10f10 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
10f20 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
10f30 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
10f40 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
10f50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
10f60 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
10f70 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
10f80 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
10f90 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
10fa0 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
10fb0 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
10fc0 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20  e table.  Doing 
10fd0 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  so is much faste
10fe0 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
10ff0 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
11000 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
11010 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
11020 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73  e table.  Becaus
11030 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74  e of this.** opt
11040 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64  imization, the d
11050 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c  eletions in "DEL
11060 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
11070 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e  are not row chan
11080 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20  ges and.** will 
11090 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62  not be counted b
110a0 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  y the sqlite3_ch
110b0 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69  anges() or [sqli
110c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
110d0 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  s()].** function
110e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  s, regardless of
110f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
11100 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72  lements that wer
11110 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  e originally.** 
11120 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54  in the table.  T
11130 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74  o get an accurat
11140 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e  e count of the n
11150 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65  umber of rows de
11160 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44  leted, use.** "D
11170 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
11180 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61   WHERE 1" instea
11190 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65  d.  Or recompile
111a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53   using the.** [S
111b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43  QLITE_OMIT_TRUNC
111c0 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e  ATE_OPTIMIZATION
111d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
111e0 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65  ption to disable
111f0 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61   the.** optimiza
11200 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72  tion on all quer
11210 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ies..**.** INVAR
11220 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
11230 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2241} The [sqlit
11240 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  e3_changes()] fu
11250 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
11260 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
11270 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  f.**          ro
11280 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11290 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
112a0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
112b0 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  TE,.**          
112c0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
112d0 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ent on the same 
112e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
112f0 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
11300 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73      within the s
11310 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72  ame or higher tr
11320 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
11330 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
11340 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
11350 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75   not been any qu
11360 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61  alifying row cha
11370 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nges..**.** {H12
11380 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20  243} Statements 
11390 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c  of the form "DEL
113a0 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61  ETE FROM tablena
113b0 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20  me" with no.**  
113c0 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c          WHERE cl
113d0 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65  ause shall cause
113e0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
113f0 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
11400 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
11410 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a  s()] to return z
11420 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20  ero, regardless 
11430 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
11440 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77     number of row
11450 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20  s originally in 
11460 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  the table..**.**
11470 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
11480 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20  .** {A12252} If 
11490 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
114a0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
114b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
114c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
114d0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
114e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
114f0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
11500 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
11510 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
11520 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63       is unpredic
11530 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11540 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11550 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
11560 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
11580 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
11590 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
115a0 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  60} <S10600>.**.
115b0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
115c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
115d0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
115e0 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53  es caused by INS
115f0 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f  ERT,.** UPDATE o
11600 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
11610 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
11620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11630 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
11640 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  ** The count inc
11650 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
11660 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67  s from all trigg
11670 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f  er contexts.  Ho
11680 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
11690 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
116a0 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
116b0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52  d to implement R
116c0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
116d0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
116e0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
116f0 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50  cessing, or DROP
11700 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e   table processin
11710 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65  g..** The change
11720 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73  s are counted as
11730 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61   soon as the sta
11740 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
11750 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d  s them is.** com
11760 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65  pleted (when the
11770 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   statement handl
11780 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  e is passed to [
11790 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
117a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
117b0 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a  finalize()])..**
117c0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
117d0 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
117e0 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
117f0 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
11800 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
11810 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
11820 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
11830 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
11840 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
11850 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
11860 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
11870 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
11880 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
11890 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20  e.)  Because of 
118a0 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
118b0 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
118c0 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
118d0 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
118e0 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
118f0 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
11900 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
11910 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
11920 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
11930 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
11940 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
11950 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
11960 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
11970 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
11980 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
11990 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
119a0 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
119b0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
119c0 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
119d0 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
119e0 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
119f0 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20  E 1" instead.   
11a00 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69  Or recompile usi
11a10 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
11a20 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f  E_OMIT_TRUNCATE_
11a30 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f  OPTIMIZATION] co
11a40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11a50 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  n to disable the
11a60 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
11a70 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e   on all queries.
11a80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
11a90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
11aa0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
11ab0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
11ac0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
11ad0 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
11ae0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11af0 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
11b00 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
11b10 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
11b20 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
11b30 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11b40 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
11b50 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
11b60 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
11b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11b80 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
11b90 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
11ba0 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
11bb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
11bc0 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
11bd0 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  eated..**.** {H1
11be0 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
11bf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
11c00 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
11c10 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
11c20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
11c30 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
11c40 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
11c50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
11c60 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
11c70 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11c80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  )]..**.** ASSUMP
11c90 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
11ca0 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
11cb0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
11cc0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
11cd0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
11ce0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
11cf0 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
11d00 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11d10 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
11d20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
11d30 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
11d40 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
11d50 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
11d60 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
11d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11d80 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
11d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11da0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
11db0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
11dc0 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30   {H12270} <S3050
11dd0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
11de0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
11df0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
11e00 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
11e10 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
11e20 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
11e30 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
11e40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
11e50 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
11e60 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
11e70 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
11e80 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
11e90 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
11ea0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
11eb0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
11ec0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
11ed0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
11ee0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
11ef0 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
11f00 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
11f10 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
11f20 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
11f30 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
11f40 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
11f50 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
11f60 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
11f70 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
11f80 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
11f90 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
11fa0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
11fb0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
11fc0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
11fd0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
11fe0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11ff0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
12000 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70  .** If an SQL op
12010 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
12020 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
12030 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
12040 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
12050 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
12060 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
12070 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
12080 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
12090 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
120a0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
120b0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
120c0 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65  **.** An SQL ope
120d0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
120e0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
120f0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
12100 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
12110 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
12120 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
12130 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
12140 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
12150 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
12160 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
12170 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
12180 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
12190 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
121a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
121b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
121c0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
121d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
121e0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
121f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
12200 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
12210 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
12220 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
12230 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
12240 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
12250 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  H12271} The [sql
12260 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12270 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
12280 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
12290 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
122a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
122b0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
122c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
122d0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
122e0 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
122f0 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
12300 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
12310 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61  tional row of da
12320 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37  ta..**.** {H1227
12330 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  2} Any SQL state
12340 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74  ment that is int
12350 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c  errupted by [sql
12360 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12370 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
12380 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12390 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
123a0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
123b0 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20  .**.** {A12279} 
123c0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
123d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
123e0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
123f0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
12400 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e            is run
12410 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
12420 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
12430 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
12440 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12450 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
12460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
12470 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
12480 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
12490 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30  Complete {H10510
124a0 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70200>.**.**
124b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
124c0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
124d0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
124e0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
124f0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
12500 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
12510 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
12520 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
12530 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
12540 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
12550 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
12560 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
12570 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
12580 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
12590 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
125a0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
125b0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
125c0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
125d0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
125e0 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
125f0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
12600 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
12610 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
12620 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
12630 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
12640 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a  a fragment of a.
12650 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ** CREATE TRIGGE
12660 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
12670 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
12680 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
12690 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
126a0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
126b0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
126c0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
126d0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
126e0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
126f0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
12700 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
12710 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
12720 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
12730 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
12740 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
12750 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ator..**.** Thes
12760 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
12770 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
12780 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
12790 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
127a0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
127b0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
127c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
127d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d  :.**.** {H10511}
127e0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76   A successful ev
127f0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  aluation of [sql
12800 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
12810 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
12820 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
12830 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73  e16()] functions
12840 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
12850 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65     return a nume
12860 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c  ric 1 if and onl
12870 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f  y if the last no
12880 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20  n-whitespace.** 
12890 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69           token i
128a0 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
128b0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
128c0 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77  t is not in betw
128d0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
128e0 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
128f0 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
12900 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
12910 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20  .**.** {H10512} 
12920 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
12930 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
12940 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e  urs during an in
12950 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  vocation.**     
12960 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33       of [sqlite3
12970 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20  _complete()] or 
12980 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
12990 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a  e16()] then the.
129a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
129b0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
129c0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
129d0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
129e0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31  NS:.**.** {A1051
129f0 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
12a00 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
12a10 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
12a20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
12a30 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
12a40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
12a50 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  A10513} The inpu
12a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
12a70 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
12a80 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
12a90 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
12aa0 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
12ab0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
12ac0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
12ad0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
12ae0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
12af0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
12b00 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
12b10 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
12b20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
12b30 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
12b40 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
12b50 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
12b60 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
12b70 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
12b80 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
12b90 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
12ba0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
12bb0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
12bc0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
12bd0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
12be0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
12bf0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
12c00 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
12c10 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
12c20 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
12c30 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
12c40 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
12c50 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
12c60 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
12c70 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
12c80 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
12c90 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
12ca0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
12cb0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
12cc0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
12cd0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
12ce0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
12cf0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
12d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
12d10 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
12d20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
12d30 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
12d40 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
12d50 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
12d60 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
12d70 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
12d80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12d90 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
12da0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
12db0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
12dc0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
12dd0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
12de0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
12df0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
12e00 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
12e10 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
12e20 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
12e30 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
12e40 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
12e50 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
12e60 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
12e70 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
12e80 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12e90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
12ea0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
12eb0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
12ec0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
12ed0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
12ee0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
12ef0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
12f00 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
12f10 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
12f20 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
12f30 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
12f40 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
12f50 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
12f60 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
12f70 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
12f80 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
12f90 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
12fa0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
12fb0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
12fc0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
12fd0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
12fe0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
12ff0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
13000 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
13010 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13020 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
13030 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
13040 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
13050 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
13060 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
13070 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
13080 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
13090 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
130a0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
130b0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
130c0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
130d0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
130e0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
130f0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
13100 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
13110 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
13120 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
13130 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
13140 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
13150 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
13160 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
13170 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
13180 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
13190 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
131a0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
131b0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
131c0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
131d0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
131e0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
131f0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
13200 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
13210 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
13220 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
13230 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
13240 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
13250 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
13260 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
13270 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
13280 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
13290 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
132a0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
132b0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
132c0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
132d0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
132e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
132f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
13300 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
13310 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
13320 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13330 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
13340 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
13350 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
13360 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
13370 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
13380 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
13390 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
133a0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
133b0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
133c0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
133d0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
133e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
133f0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
13400 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
13410 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
13420 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
13430 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
13440 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
13450 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
13460 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
13470 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
13480 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
13490 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
134a0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
134b0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
134c0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
134d0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
134e0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
134f0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
13500 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
13510 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
13520 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
13530 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
13540 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
13550 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
13560 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
13570 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
13580 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
13590 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
135a0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
135b0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
135c0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
135d0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=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 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
13600 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13610 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
13620 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
13630 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
13640 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
13650 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
13660 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13670 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
13680 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
13690 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
136a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
136b0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
136c0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
136d0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
136e0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
136f0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
13700 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
13710 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
13720 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
13730 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
13740 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
13750 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
13760 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
13770 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
13780 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
13790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
137a0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
137b0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
137c0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
137d0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
137e0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
137f0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41  ior..** .** INVA
13800 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
13810 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  12311} The [sqli
13820 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13830 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f  (D,C,A)] functio
13840 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a  n shall replace.
13850 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79  **          busy
13860 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
13870 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13880 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20  ction] D with a 
13890 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
138a0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
138b0 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61  er C and applica
138c0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
138d0 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  r A..**.** {H123
138e0 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65  12} Newly create
138f0 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
13900 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68  ections] shall h
13910 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20  ave a busy.**   
13920 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f         handler o
13930 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  f NULL..**.** {H
13940 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
13950 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73  or more [databas
13960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
13970 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20  hare a.**       
13980 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
13990 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20  le_shared_cache 
139a0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c  | common cache],
139b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
139c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
139d0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
139e0 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
139f0 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
13a00 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
13a10 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
13a20 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
13a30 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
13a40 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36  k..**.** {H12316
13a50 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
13a60 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
13a70 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
13a80 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
13a90 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
13aa0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
13ab0 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
13ac0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53   shall return [S
13ad0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
13ae0 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69  ** {H12318} SQLi
13af0 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73  te shall invokes
13b00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13b10 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
13b20 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20  ents which.**   
13b30 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70         are a cop
13b40 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
13b50 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
13b60 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
13b70 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
13b80 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13b90 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
13ba0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
13bb0 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20   of prior.**    
13bc0 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
13bd0 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61  s of the busy ha
13be0 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61  ndler for the sa
13bf0 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
13c00 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
13c10 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33  ONS:.**.** {A123
13c20 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c  19} A busy handl
13c30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
13c40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
13c50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
13c60 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72        or [prepar
13c70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
13c80 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
13c90 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
13ca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13cb0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
13cc0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
13cd0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
13ce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
13cf0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
13d00 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
13d10 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
13d20 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
13d30 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13d40 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
13d50 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
13d60 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
13d70 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
13d80 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
13d90 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
13da0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
13db0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
13dc0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
13dd0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
13de0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13df0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
13e00 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
13e10 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
13e20 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
13e30 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
13e40 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
13e50 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
13e60 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
13e70 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
13e80 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
13e90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
13ea0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
13eb0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
13ec0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
13ed0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
13ee0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
13ef0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
13f00 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
13f10 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
13f20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
13f30 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
13f40 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
13f50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13f60 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
13f70 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
13f80 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
13f90 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
13fa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
13fb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
13fc0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
13fd0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
13fe0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
13ff0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
14000 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
14010 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
14020 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
14030 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
14040 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
14050 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20  ll override any 
14060 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
14070 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
14080 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
14090 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
140a0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
140b0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
140c0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
140d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
140e0 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20  .** {H12343} If 
140f0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
14100 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
14110 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
14120 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
14130 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
14140 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
14150 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73  e busy handler s
14160 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20  hall be cleared 
14170 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  so that.**      
14180 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65      all subseque
14190 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  nt locking event
141a0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65  s immediately re
141b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
141c0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  Y]..**.** {H1234
141d0 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  4} If the 2nd pa
141e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
141f0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
14200 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76  ()] is a positiv
14210 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
14220 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62  mber N, then a b
14230 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
14240 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65  l be set that re
14250 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
14260 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
14270 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
14280 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  n the [sqlite3_v
14290 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61  fs | VFS interfa
142a0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ce] until.**    
142b0 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65        either the
142c0 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
142d0 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
142e0 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a  tive sleep time.
142f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f  **          repo
14300 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c  rted back by xSl
14310 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
14320 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
14330 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
14340 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
14350 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
14360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14370 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
14380 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
14390 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
143a0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
143b0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
143c0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
143d0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
143e0 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
143f0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
14400 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14410 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14420 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14430 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14440 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14450 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14460 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14470 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
14480 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
14490 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
144a0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
144b0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
144c0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
144d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
144e0 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
144f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
14500 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
14510 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14520 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14530 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14540 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14550 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14560 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14570 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
14580 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
14590 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
145a0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
145b0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
145c0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
145d0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
145e0 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
145f0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14600 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14610 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14620 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14630 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14640 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14650 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14660 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14670 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
14680 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
14690 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
146a0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
146b0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
146c0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
146d0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
146e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
146f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
14700 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
14710 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14720 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14730 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14740 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14750 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14760 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14770 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
14780 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
14790 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
147a0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
147b0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
147c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
147d0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
147e0 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
147f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
14800 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
14810 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
14820 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
14830 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14840 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
14850 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
14860 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
14870 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
14880 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
14890 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
148a0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
148b0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
148c0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
148d0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
148e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
148f0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
14900 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
14910 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
14920 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
14930 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
14940 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
14950 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
14960 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
14970 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
14980 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
14990 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
149a0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
149b0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
149c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
149d0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
149e0 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
149f0 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
14a00 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
14a10 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
14a20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
14a30 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
14a40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a50 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
14a60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14a70 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
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 35 5d 20 3d 20 22 32  sult&#91;5] = "2
14aa0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
14ab0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
14ac0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
14ad0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14ae0 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
14af0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14b00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
14b10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14b20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
14b30 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
14b40 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
14b50 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
14b60 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
14b70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
14b80 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
14b90 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
14ba0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
14bb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
14bc0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
14bd0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
14be0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
14bf0 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
14c00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
14c10 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
14c20 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
14c30 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
14c40 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
14c50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
14c60 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
14c70 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
14c80 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
14c90 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
14ca0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
14cb0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
14cc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
14cd0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
14ce0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
14cf0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
14d00 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
14d10 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
14d20 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
14d30 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
14d40 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
14d50 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14d60 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
14d70 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
14d80 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
14d90 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
14da0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14db0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
14dc0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
14dd0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
14de0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
14df0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
14e00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14e10 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
14e20 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
14e30 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
14e40 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
14e50 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
14e60 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
14e70 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
14e80 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
14e90 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
14ea0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
14eb0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
14ec0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
14ed0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
14ee0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
14ef0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
14f00 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
14f10 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
14f20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
14f30 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
14f40 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
14f50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
14f60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31  S:.**.** {H12371
14f70 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
14f80 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
14f90 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
14fa0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
14fb0 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c           it shal
14fc0 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c  l free the resul
14fd0 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
14fe0 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
14ff0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
15000 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
15010 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62  ss, skip any sub
15020 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
15030 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   set the.**     
15040 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20       *pazResult 
15050 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
15060 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
15070 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
15080 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d  ..**.** {H12373}
15090 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e   If the pnColumn
150a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
150b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
150c0 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
150d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
150e0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
150f0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
15100 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
15110 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
15120 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75      write the nu
15130 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
15140 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
15150 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
15160 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
15170 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  *pnColumn..**.**
15180 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65   {H12374} If the
15190 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72   pnRow parameter
151a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
151b0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
151c0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
151d0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
151e0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
151f0 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
15200 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
15210 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73            writes
15220 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
15230 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
15240 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
15250 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
15260 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a  nto *pnRow..**.*
15270 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63  * {H12376} A suc
15280 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
15290 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
152a0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74  et_table()] that
152b0 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20   computes.**    
152c0 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20        N rows of 
152d0 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f  result with C co
152e0 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68  lumns per row sh
152f0 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73  all make *pazRes
15300 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
15310 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61  point to an arra
15320 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
15330 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73   (N+1)*C strings
15340 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
15350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73  .**          C s
15360 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d  trings are colum
15370 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69  n names as obtai
15380 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ned from.**     
15390 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
153a0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
153b0 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f   the rest are co
153c0 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75  lumn result valu
153d0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
153e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
153f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
15400 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  t()]..**.** {H12
15410 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20  379} The values 
15420 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74  in the pazResult
15430 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20   array returned 
15440 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  by [sqlite3_get_
15450 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  table()].**     
15460 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69       shall remai
15470 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c  n valid until cl
15480 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eared by [sqlite
15490 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
154a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20  .**.** {H12382} 
154b0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
154c0 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c  curs during eval
154d0 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
154e0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
154f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
15500 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73  function shall s
15510 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f  et *pazResult to
15520 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20   NULL, write an 
15530 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
15540 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d            into m
15550 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
15560 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
15570 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20  loc()], make.** 
15580 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72           **pzErr
15590 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61  msg point to tha
155a0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c  t error message,
155b0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a   and return a.**
155c0 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
155d0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
155e0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
155f0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
15600 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
15610 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
15620 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
15630 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
15640 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
15650 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
15660 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
15670 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
15680 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
15690 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
156a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
156b0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
156c0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
156d0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
156e0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
156f0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
15700 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
15710 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
15720 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
15730 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
15740 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
15750 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
15760 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
15770 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
15780 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
15790 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
157a0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37  g Functions {H17
157b0 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32  400} <S70000><S2
157c0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0000>.**.** Thes
157d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
157e0 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
157f0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
15800 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
15810 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
15820 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
15830 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
15840 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
15850 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
15860 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
15870 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
15880 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
15890 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
158a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
158b0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
158c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
158d0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
158e0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
158f0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
15900 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20  _free()].  Both 
15910 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15920 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
15930 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
15940 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
15950 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
15960 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
15970 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
15980 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
15990 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
159a0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
159b0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
159c0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
159d0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
159e0 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
159f0 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
15a00 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
15a10 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
15a20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15a30 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
15a40 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
15a50 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15a60 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
15a70 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
15a80 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
15a90 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
15aa0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
15ab0 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
15ac0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
15ad0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
15ae0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
15af0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
15b00 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
15b10 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
15b20 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
15b30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15b40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
15b50 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
15b60 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
15b70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
15b80 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
15b90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
15ba0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
15bb0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
15bc0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
15bd0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
15be0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
15bf0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
15c00 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
15c10 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
15c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
15c30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15c40 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
15c50 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
15c60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
15c70 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
15c80 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
15c90 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
15ca0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15cb0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
15cc0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
15cd0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
15ce0 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
15cf0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
15d00 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
15d10 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
15d20 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
15d30 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
15d40 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
15d50 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
15d60 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
15d70 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
15d80 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
15d90 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
15da0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
15db0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
15dc0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
15dd0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
15de0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
15df0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
15e00 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
15e10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
15e20 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
15e30 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
15e40 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
15e50 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
15e60 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
15e70 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
15e80 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
15e90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
15ea0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
15eb0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
15ec0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
15ed0 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
15ee0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
15ef0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
15f00 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
15f10 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
15f20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
15f30 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
15f40 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
15f50 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
15f60 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
15f70 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
15f80 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
15f90 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
15fa0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
15fb0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
15fc0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
15fd0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
15fe0 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
15ff0 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
16000 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
16010 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16020 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16030 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
16040 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
16050 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
16060 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16070 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
16080 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
16090 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
160a0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
160b0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
160c0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
160d0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
160e0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
160f0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
16100 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
16110 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
16120 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
16130 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
16140 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
16150 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16160 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
16170 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
16180 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
16190 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
161a0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
161b0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
161c0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
161d0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
161e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
161f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
16200 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
16210 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
16220 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
16230 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16240 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
16250 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
16260 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
16270 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
16280 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
16290 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
162a0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
162b0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
162c0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
162d0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
162e0 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
162f0 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
16300 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16310 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
16320 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
16330 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
16340 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
16350 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
16360 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
16370 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
16380 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
16390 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
163a0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
163b0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
163c0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
163d0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
163e0 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
163f0 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
16400 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
16410 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
16420 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
16430 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
16440 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
16450 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16460 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
16470 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
16480 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
16490 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  le quotes) in pl
164a0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
164b0 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
164c0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
164d0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
164e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
164f0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
16500 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16510 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
16520 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
16530 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
16540 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
16550 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
16560 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
16570 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
16580 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
16590 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
165a0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
165b0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
165c0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
165d0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
165e0 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
165f0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
16600 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
16610 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
16620 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
16630 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
16640 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
16650 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
16660 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
16670 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
16680 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
16690 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
166a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
166b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
166c0 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44  put string. {END
166d0 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  }.**.** INVARIAN
166e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  TS:.**.** {H1740
166f0 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  3}  The [sqlite3
16700 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20  _mprintf()] and 
16710 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  [sqlite3_vmprint
16720 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  f()] interfaces.
16730 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
16740 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74  urn either point
16750 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
16760 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
16770 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20  ings held in.** 
16780 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
16790 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
167a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
167b0 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ] or NULL pointe
167c0 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  rs if.**        
167d0 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71     a call to [sq
167e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
167f0 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fails..**.** {H1
16800 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69  7406}  The [sqli
16810 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
16820 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73  interface writes
16830 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
16840 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
16850 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74  UTF-8 string int
16860 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69  o the buffer poi
16870 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73  nted to by the s
16880 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
16890 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f  **           pro
168a0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66  vided that the f
168b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
168c0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
168d0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ero..**.** {H174
168e0 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  07}  The [sqlite
168f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
16900 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
16910 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a   write slots of.
16920 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73  **           its
16930 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28   output buffer (
16940 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16950 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68  eter) outside th
16960 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20  e range.**      
16970 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67       of 0 throug
16980 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69  h N-1 (where N i
16990 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
169a0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20  meter).**       
169b0 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f      regardless o
169c0 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  f the length of 
169d0 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  the string.**   
169e0 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65          requeste
169f0 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20  d by the format 
16a00 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
16a10 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
16a20 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
16a30 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
16a40 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
16a50 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
16a60 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
16a70 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
16a80 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
16a90 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
16aa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
16ab0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
16ac0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
16ad0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
16ae0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
16af0 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
16b00 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
16b10 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
16b20 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
16b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
16b40 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
16b50 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
16b60 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
16b70 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
16b80 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
16b90 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
16ba0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
16bb0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
16bc0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
16bd0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
16be0 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
16bf0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
16c00 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
16c10 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
16c20 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
16c30 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
16c40 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
16c50 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
16c60 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
16c70 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
16c80 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
16c90 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
16ca0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
16cb0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
16cc0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
16cd0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
16ce0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
16cf0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
16d00 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
16d10 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
16d20 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
16d30 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
16d40 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
16d50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16d60 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
16d70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
16d80 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16d90 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
16da0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16db0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
16dc0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
16dd0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
16de0 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
16df0 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
16e00 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
16e10 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
16e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
16e30 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
16e40 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
16e50 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
16e60 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
16e70 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
16e80 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
16e90 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
16ea0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
16eb0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
16ec0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
16ed0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
16ee0 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
16ef0 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
16f00 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
16f10 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
16f20 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
16f30 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
16f40 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
16f50 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
16f60 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
16f70 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
16f80 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
16f90 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
16fa0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
16fb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
16fc0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
16fd0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
16fe0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61   The sqlite3_rea
16ff0 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
17000 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
17010 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
17020 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17030 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
17040 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
17050 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
17060 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
17070 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
17080 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
17090 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
170a0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  * parameter.  If
170b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
170c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
170d0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
170e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
170f0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
17100 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
17110 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
17120 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
17130 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
17140 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17150 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17160 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65  ()..** If the se
17170 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
17180 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
17190 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a  c() is zero or.*
171a0 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  * negative then 
171b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
171c0 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65  exactly the same
171d0 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   as calling.** s
171e0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77  qlite3_free(P) w
171f0 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69  here P is the fi
17200 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
17210 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17220 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  ()..** sqlite3_r
17230 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
17240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
17250 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17260 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
17270 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
17280 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
17290 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
172a0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
172b0 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a   If M is the siz
172c0 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  e of the prior a
172d0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
172e0 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a  min(N,M) bytes.*
172f0 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61  * of the prior a
17300 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f  llocation are co
17310 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65  pied into the be
17320 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65  ginning of buffe
17330 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  r returned.** by
17340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17350 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  () and the prior
17360 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
17370 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  reed..** If sqli
17380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
17390 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
173a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
173b0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
173c0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  freed..**.** The
173d0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
173e0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
173f0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
17400 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
17410 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
17420 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
17430 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20   byte boundary. 
17440 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
17450 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e  default implemen
17460 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65  tation of the me
17470 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17480 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a  subsystem uses.*
17490 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20  * the malloc(), 
174a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
174b0 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79  ee() provided by
174c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
174d0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37  library..** {H17
174e0 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66  382} However, if
174f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
17500 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
17510 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49  SQLITE_MEMORY_SI
17520 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20  ZE=<i>NNN</i> C 
17530 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
17540 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e  ro (where <i>NNN
17550 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e  </i>.** is an in
17560 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c  teger), then SQL
17570 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61  ite create a sta
17580 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20  tic array of at 
17590 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c  least.** <i>NNN<
175a0 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  /i> bytes in siz
175b0 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20  e and uses that 
175c0 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66  array for all of
175d0 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20   its dynamic.** 
175e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
175f0 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20  n needs. {END}  
17600 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72  Additional memor
17610 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69  y allocator opti
17620 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64  ons.** may be ad
17630 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
17640 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e  leases..**.** In
17650 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
17660 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
17670 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
17680 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
17690 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
176a0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
176b0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
176c0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
176d0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
176e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
176f0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
17700 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
17710 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
17720 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
17730 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
17740 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
17750 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
17760 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
17770 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
17780 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
17790 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
177a0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
177b0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
177c0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
177d0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
177e0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
177f0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
17800 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
17810 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
17820 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
17830 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
17840 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
17850 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17860 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
17870 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
17880 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
17890 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
178a0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
178b0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
178c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
178d0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
178e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
178f0 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b   {H17303}  The [
17900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
17910 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
17920 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
17930 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
17940 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68        a newly ch
17950 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20  ecked-out block 
17960 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
17970 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  tes of memory.**
17980 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
17990 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
179a0 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73  d, or it returns
179b0 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75   NULL if it is u
179c0 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
179d0 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68     to fulfill th
179e0 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a  e request..**.**
179f0 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b   {H17304}  The [
17a00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
17a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
17a20 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
17a30 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ter if.**       
17a40 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68      N is less th
17a50 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
17a60 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  ero..**.** {H173
17a70 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  05}  The [sqlite
17a80 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72  3_free(P)] inter
17a90 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65  face releases me
17aa0 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a  mory previously.
17ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
17ac0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
17ad0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
17ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17af0 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
17b00 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61     making it ava
17b10 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65  ilable for reuse
17b20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d  ..**.** {H17306}
17b30 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17b40 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d  ite3_free(NULL)]
17b50 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
17b60 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  o-op..**.** {H17
17b70 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  310}  A call to 
17b80 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17b90 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61  (0,N)] is equiva
17ba0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
17bb0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
17bc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
17bd0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  )]..**.** {H1731
17be0 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  2}  A call to [s
17bf0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
17c00 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,0)] is equivale
17c10 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
17c20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
17c30 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a  lite3_free(P)]..
17c40 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20  **.** {H17315}  
17c50 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
17c60 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61  uses [sqlite3_ma
17c70 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
17c80 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
17c90 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b             and [
17ca0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
17cb0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d  for all of its m
17cc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17cd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
17ce0 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e    deallocation n
17cf0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  eeds..**.** {H17
17d00 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  318}  The [sqlit
17d10 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
17d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17d30 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
17d40 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
17d50 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63   to a block of c
17d60 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72  hecked-out memor
17d70 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  y of at least N 
17d80 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a  bytes in size.**
17d90 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20             that 
17da0 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  is 8-byte aligne
17db0 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  d, or a NULL poi
17dc0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  nter..**.** {H17
17dd0 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  321}  When [sqli
17de0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
17df0 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
17e00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
17e10 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
17e20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66      copies the f
17e30 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20  irst K bytes of 
17e40 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69  content from P i
17e50 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a  nto the newly.**
17e60 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63             alloc
17e70 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72  ated block, wher
17e80 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65  e K is the lesse
17e90 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73  r of N and the s
17ea0 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ize of.**       
17eb0 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20 50      the buffer P
17ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d  ..**.** {H17322}
17ed0 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
17ee0 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
17ef0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
17f00 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
17f10 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
17f20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66  releases the buf
17f30 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fer P..**.** {H1
17f40 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7323}  When [sql
17f50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
17f60 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  )] returns NULL,
17f70 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73   the buffer P is
17f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
17f90 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65  t modified or re
17fa0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53  leased..**.** AS
17fb0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
17fc0 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20 70   {A17350}  The p
17fd0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
17fe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
17ff0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
18000 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
18010 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62            must b
18020 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
18030 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
18040 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
18050 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
18060 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20    invocation of 
18070 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18080 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
18090 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
180a0 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
180b0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
180c0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  leased..**.** {A
180d0 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c  17351}  The appl
180e0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
180f0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
18100 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20  ny part of.**   
18110 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20          a block 
18120 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
18130 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
18140 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ased using.**   
18150 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18160 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
18170 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
18180 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
18190 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
181a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
181b0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
181c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
181d0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
181e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
181f0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
18200 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 30  atistics {H17370
18210 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a  } <S30210>.**.**
18220 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
18230 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
18240 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
18250 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
18260 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
18270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
18280 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18290 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
182a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
182b0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
182c0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
182d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
182e0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
182f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
18300 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65  .** {H17371} The
18310 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
18320 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
18330 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
18340 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
18350 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f           of memo
18360 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
18370 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
18380 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
18390 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33  )..**.** {H17373
183a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
183b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
183c0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
183d0 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
183e0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
183f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
18400 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
18410 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
18420 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20   mark.**        
18430 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74    was last reset
18440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d  ..**.** {H17374}
18450 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   The values retu
18460 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
18470 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18480 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
18490 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
184a0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
184b0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
184c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64  d.**          ad
184d0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e  ded by SQLite in
184e0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   its implementat
184f0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
18500 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  malloc()],.**   
18510 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f         but not o
18520 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
18530 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
18540 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
18550 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ry.**          r
18560 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
18570 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
18580 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
18590 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d  {H17375} The mem
185a0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
185b0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
185c0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
185d0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
185e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
185f0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
18600 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
18610 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
18620 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
18630 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18640 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65 20  ] is true.  The 
18650 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
18660 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
18670 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
18680 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
18690 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
186a0 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  rk.**          p
186b0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
186c0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
186d0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
186e0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
186f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
18700 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18710 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
18720 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
18730 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
18740 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
18750 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c  rator {H17390} <
18760 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  S20000>.**.** SQ
18770 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
18780 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
18790 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
187a0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
187b0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
187c0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
187d0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
187e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
187f0 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
18800 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
18810 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
18820 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
18830 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
18840 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
18850 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
18860 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
18870 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
18880 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
18890 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
188a0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
188b0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
188c0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
188d0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
188e0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
188f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
18900 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
18910 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
18920 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
18930 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
18940 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
18950 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
18960 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
18970 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18980 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
18990 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
189a0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
189b0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
189c0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
189d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
189e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
189f0 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
18a00 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
18a10 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
18a20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
18a30 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
18a40 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
18a50 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
18a60 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
18a70 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
18a80 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
18a90 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
18aa0 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  H17392} The [sql
18ab0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
18ac0 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
18ad0 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
18ae0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
18af0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
18b00 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
18b10 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
18b20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
18b30 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
18b40 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
18b50 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
18b60 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
18b70 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
18b80 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
18b90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
18ba0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
18bb0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18bc0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
18bd0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
18be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
18bf0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
18c00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
18c10 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
18c20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18c30 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
18c40 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
18c50 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
18c60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18c70 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
18c80 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
18c90 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
18ca0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
18cb0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
18cc0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18cd0 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
18ce0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
18cf0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
18d00 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
18d10 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
18d20 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
18d30 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
18d40 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
18d50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18d60 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
18d70 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
18d80 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
18d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18da0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
18db0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
18dc0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
18dd0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
18de0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
18df0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
18e00 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
18e10 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
18e20 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
18e30 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
18e40 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
18e50 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
18e60 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
18e70 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
18e80 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
18e90 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
18ea0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18eb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18ec0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
18ed0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
18ee0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
18ef0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
18f00 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
18f10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18f20 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
18f30 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
18f40 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
18f50 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
18f60 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
18f70 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
18f80 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
18f90 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
18fa0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
18fb0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
18fc0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
18fd0 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
18fe0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18ff0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
19000 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19010 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
19020 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
19030 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
19040 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
19050 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
19060 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
19070 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
19080 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
19090 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
190a0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
190b0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
190c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
190d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
190e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
190f0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
19100 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
19110 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
19120 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
19130 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
19140 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
19150 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
19160 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
19170 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
19180 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
19190 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
191a0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
191b0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
191c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
191d0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
191e0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
191f0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
19200 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
19210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19220 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
19230 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19240 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
19250 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
19260 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
19270 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
19280 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
19290 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
192a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
192b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
192c0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
192d0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
192e0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
192f0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
19300 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
19310 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19320 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
19330 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
19340 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
19350 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
19360 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
19370 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
19380 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
19390 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
193a0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
193b0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
193c0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
193d0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
193e0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
193f0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
19400 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
19410 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
19420 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
19430 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
19440 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
19450 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
19460 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
19470 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
19480 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
19490 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
194a0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
194b0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
194c0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
194d0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
194e0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
194f0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
19500 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
19510 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
19520 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
19530 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
19540 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
19550 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
19560 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
19570 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
19580 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
19590 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
195a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
195b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
195c0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
195d0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
195e0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
195f0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
19600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19610 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
19620 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
19630 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
19640 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
19650 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
19660 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
19670 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
19680 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
19690 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
196a0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
196b0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
196c0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
196d0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
196e0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
196f0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
19700 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
19710 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
19720 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
19730 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
19740 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
19750 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
19760 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
19770 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
19780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19790 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
197a0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
197b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
197c0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
197d0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
197e0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
197f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
19800 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
19810 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
19820 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
19830 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
19840 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
19850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19860 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
19870 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
19880 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
19890 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
198a0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
198b0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
198c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
198d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
198e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
198f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
19900 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
19910 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
19920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
19930 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
19940 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
19950 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
19960 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
19970 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
19980 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
19990 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
199a0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
199b0 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61  might be reprepa
199c0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
199d0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
199e0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
199f0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
19a00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19a10 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
19a20 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
19a30 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
19a40 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
19a50 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
19a60 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19a70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  )]..**.** Note t
19a80 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
19a90 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19aa0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
19ab0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
19ac0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
19ad0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
19ae0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
19af0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
19b00 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
19b10 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
19b20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
19b30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
19b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
19b60 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
19b70 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
19b80 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
19b90 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
19ba0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
19bb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19bc0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
19bd0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
19be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19bf0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
19c00 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
19c10 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
19c20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70  parseed and comp
19c30 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  iled..**.** {H12
19c40 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
19c50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19c60 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
19c70 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
19c80 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19c90 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
19ca0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
19cb0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a  E_DENY], then.**
19cc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70            the ap
19cd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  plication interf
19ce0 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ace call that ca
19cf0 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
19d00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19d10 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
19d20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
19d30 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
19d40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
19d50 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
19d60 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
19d70 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
19d80 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {H12504} When t
19d90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19da0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
19db0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
19dc0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
19dd0 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
19de0 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72  is processed nor
19df0 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mally..**.** {H1
19e00 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
19e10 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19e20 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19e30 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
19e40 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63            applic
19e50 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20  ation interface 
19e60 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
19e70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
19e80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19e90 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
19ea0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
19eb0 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
19ec0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
19ed0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
19ee0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
19ef0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
19f00 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
19f10 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
19f20 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
19f30 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
19f40 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
19f50 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19f60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
19f70 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
19f80 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
19f90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19fa0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
19fb0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19fc0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
19fd0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
19fe0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
19ff0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
1a000 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
1a010 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1a020 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1a030 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1a040 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
1a050 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
1a060 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1a070 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
1a080 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
1a090 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a0a0 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
1a0b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1a0c0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
1a0d0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
1a0e0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
1a0f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
1a100 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
1a110 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
1a120 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
1a130 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
1a140 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
1a150 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
1a160 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
1a170 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a190 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a1a0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
1a1b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1a1c0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1a1d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a1e0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
1a1f0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
1a200 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a210 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1a220 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1a230 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
1a240 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1a250 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1a260 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
1a270 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
1a280 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
1a290 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1a2a0 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
1a2b0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1a2c0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
1a2d0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1a2e0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
1a2f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a300 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1a310 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
1a320 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
1a330 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1a340 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a350 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
1a360 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
1a370 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
1a380 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
1a390 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
1a3a0 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
1a3b0 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
1a3c0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
1a3d0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
1a3e0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
1a3f0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
1a400 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
1a410 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1a420 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
1a430 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
1a440 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
1a450 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1a460 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a470 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1a480 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1a490 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1a4a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a4b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1a4c0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1a4d0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1a4e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a4f0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1a500 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
1a510 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
1a520 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1a530 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1a540 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a550 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1a560 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1a570 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1a580 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1a590 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1a5a0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1a5b0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1a5c0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1a5d0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1a5e0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1a5f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a600 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1a610 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1a620 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1a630 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1a640 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a650 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1a660 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1a670 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1a680 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1a690 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1a6a0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1a6b0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1a6c0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1a6d0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1a6e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1a6f0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1a700 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
1a710 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
1a720 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a730 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a740 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a750 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a760 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a770 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a780 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a790 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a7a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a7b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a7c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a7d0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a7e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a7f0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a800 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a810 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1a820 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1a830 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1a840 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a850 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1a860 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1a870 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1a880 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1a890 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1a8a0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1a8b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1a8c0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1a8d0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1a8e0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1a8f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1a900 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1a910 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1a920 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1a930 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1a940 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a950 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1a960 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1a970 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1a980 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a990 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1a9a0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1a9b0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1a9c0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1a9d0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
1a9e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a9f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1aa00 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1aa10 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1aa20 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1aa30 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1aa40 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1aa50 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1aa60 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1aa70 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1aa80 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1aa90 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1aaa0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
1aab0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1aac0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
1aad0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1aae0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
1aaf0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
1ab00 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1ab10 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
1ab20 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74   shall be an int
1ab30 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
1ab40 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ab50 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1ab60 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
1ab70 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
1ab80 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
1ab90 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1aba0 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20  ** {H12552} The 
1abb0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1abc0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  meters to the.**
1abd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1abe0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1abf0 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
1ac00 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20  n callback].**  
1ac10 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1ac20 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1ac30 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1ac40 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
1ac50 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
1ac60 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
1ac70 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
1ac80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ac90 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
1aca0 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
1acb0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1acc0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1acd0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ace0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1acf0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ad00 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1ad10 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
1ad20 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
1ad30 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
1ad40 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1ad50 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  le..**.** {H1255
1ad60 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
1ad70 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1ad80 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ad90 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ada0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1adb0 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1adc0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1add0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
1ade0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1adf0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ae00 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ae10 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
1ae20 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1ae30 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1ae40 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1ae50 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1ae60 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
1ae70 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1ae80 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1aeb0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1aec0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1aed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1aee0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1aef0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1af00 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1af10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1af20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1af30 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1af40 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1af50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1af60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1af70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1af80 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1af90 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1afa0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1afb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1afc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1afd0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1afe0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1aff0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b000 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b010 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b020 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1b030 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1b040 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b050 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b060 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b070 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1b080 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1b090 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b0a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b0b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b0c0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1b0d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b0e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b0f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b100 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b110 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1b120 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b130 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b140 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b150 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1b160 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1b170 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b180 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b190 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b1a0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1b1b0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1b1c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b1d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b1e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b1f0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1b200 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1b210 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b220 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b230 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b240 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1b250 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1b260 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b270 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b280 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b290 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1b2a0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1b2b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b2c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b2d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b2e0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1b2f0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1b300 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b310 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b330 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1b340 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1b350 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b360 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b380 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1b390 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1b3a0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b3b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b3d0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1b3e0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1b3f0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b400 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1b420 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1b430 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1b440 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b450 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1b470 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1b480 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1b490 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1b4a0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1b4b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1b4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b4d0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1b4e0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1b4f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1b500 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1b510 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b520 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1b530 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1b540 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b550 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1b560 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1b570 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
1b580 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b590 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b5a0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1b5b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1b5c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b5d0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b5e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b5f0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1b600 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1b610 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1b620 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b630 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b640 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1b650 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1b660 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1b670 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1b680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b690 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1b6a0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1b6b0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1b6c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b6d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b6e0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1b6f0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1b700 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b710 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b730 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1b740 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1b750 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b760 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b780 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1b790 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1b7a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b7b0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1b7c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b7d0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1b7e0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1b7f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1b800 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1b810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b820 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1b830 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1b840 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1b850 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1b860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b870 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1b880 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1b890 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1b8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b8b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1b8c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
1b8d0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
1b8e0 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
1b8f0 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
1b900 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1b910 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b920 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1b930 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1b940 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1b950 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1b960 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1b970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
1b980 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1b990 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1b9a0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1b9b0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1b9c0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1b9d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1b9e0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1b9f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ba00 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
1ba10 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
1ba20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1ba30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1ba40 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
1ba50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1ba60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1ba70 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
1ba80 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
1ba90 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1baa0 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1bab0 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1bac0 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1bad0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1bae0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1baf0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1bb00 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1bb10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
1bb20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1bb30 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1bb40 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1bb50 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1bb60 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1bb70 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
1bb80 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1bb90 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1bba0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1bbb0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1bbc0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1bbd0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1bbe0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1bbf0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1bc00 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49   to run..**.** I
1bc10 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1bc20 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
1bc30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bc40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
1bc50 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
1bc60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1bc70 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1bc80 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
1bc90 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  er an SQL statem
1bca0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1bcb0 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a   to execute and.
1bcc0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
1bcd0 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73  ever a trigger s
1bce0 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20  ubprogram first 
1bcf0 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a  begins to run..*
1bd00 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61  *.** {H12282} Ea
1bd10 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
1bd20 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61  te3_trace()] sha
1bd30 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  ll override the 
1bd40 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
1bd50 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
1bd60 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
1bd70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
1bd80 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
1bd90 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73  llback shall dis
1bda0 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  able tracing..**
1bdb0 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65  .** {H12284} The
1bdc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1bdd0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1bde0 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61  lback shall be a
1bdf0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1be00 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72       the pointer
1be10 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33   which was the 3
1be20 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  rd argument to [
1be30 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
1be40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d  ..**.** {H12285}
1be50 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1be60 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1be70 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1be80 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1be90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1bea0 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
1beb0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1bec0 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   text.**        
1bed0 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61    of the SQL sta
1bee0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1bef0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71   passed into [sq
1bf00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bf10 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1bf20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
1bf30 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  t, or an SQL com
1bf40 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20  ment indicating 
1bf50 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  the beginning.**
1bf60 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74            of a t
1bf70 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
1bf80 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37  m..**.** {H12287
1bf90 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
1bfa0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1bfb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1bfc0 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76  rofile()] is inv
1bfd0 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
1bfe0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1bff0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1c000 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20  .**.** {H12288} 
1c010 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1c020 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1c030 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1c040 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1c050 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72       the 3rd par
1c060 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1c070 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a  e3_profile()]..*
1c080 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68  *.** {H12289} Th
1c090 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c0a0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
1c0b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1c0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1c0d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1c0e0 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f  8 string that co
1c0f0 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c  ntains the compl
1c100 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20  ete text of.**  
1c110 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20          the SQL 
1c120 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
1c130 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79  was processed by
1c140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c150 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
1c160 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
1c170 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alent..**.** {H1
1c180 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20  2290} The third 
1c190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c1a0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c1b0 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  k is an estimate
1c1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1c1d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
1c1e0 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c  noseconds of wal
1c1f0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71  l-clock time req
1c200 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  uired to.**     
1c210 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c       run the SQL
1c220 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20   statement from 
1c230 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e  start to finish.
1c240 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
1c250 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1c260 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1c270 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1c280 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1c290 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1c2a0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1c2b0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1c2c0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1c2d0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1c2e0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1c2f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1c300 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1c310 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c320 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1c330 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  s Callbacks {H12
1c340 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  910} <S60400>.**
1c350 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c360 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
1c370 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c380 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
1c390 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
1c3a0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
1c3b0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1c3c0 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
1c3d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1c3e0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1c3f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1c400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c410 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
1c420 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1c430 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1c440 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1c450 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1c460 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1c470 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
1c480 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1c490 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1c4a0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1c4b0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1c4c0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1c4d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1c4e0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1c4f0 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1c500 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1c510 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1c520 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1c530 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c540 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1c550 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1c560 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c570 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c580 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1c590 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1c5a0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1c5b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1c5c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1c5d0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1c5e0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1c5f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1c600 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1c610 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1c620 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1c630 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1c640 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68  *.** {H12911} Th
1c650 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1c660 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1c670 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  y sqlite3_progre
1c680 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
1c690 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
1c6a0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1c6b0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1c6c0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1c6d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c6e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1c6f0 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70  * {H12912} The p
1c700 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1c710 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
1c720 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
1c730 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
1c740 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
1c750 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1c760 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c770 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1c780 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
1c790 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1c7a0 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73   call that regis
1c7b0 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
1c7c0 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20    the callback. 
1c7d0 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
1c7e0 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72  an 1, sqlite3_pr
1c7f0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1c800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74  .**          act
1c810 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70  s as if a NULL p
1c820 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c830 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69  had been specifi
1c840 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1c850 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
1c860 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
1c870 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1c880 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
1c890 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
1c8a0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
1c8b0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a  ess_handler()..*
1c8c0 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68  *.** {H12914} Th
1c8d0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1c8e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  t to sqlite3_pro
1c8f0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20  gress_handler() 
1c900 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1c910 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
1c920 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
1c930 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
1c940 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
1c950 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20  on each time it 
1c960 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
1c970 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20  * {H12915} If a 
1c980 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1c990 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73  _step()] results
1c9a0 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
1c9b0 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20   opcodes.**     
1c9c0 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75       being execu
1c9d0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ted, then the pr
1c9e0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1c9f0 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
1ca00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d  ..**.** {H12916}
1ca10 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b   Every call to [
1ca20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1ca30 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
1ca40 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
1ca50 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  es any previousl
1ca60 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f  y registered pro
1ca70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1ca80 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66  *.** {H12917} If
1ca90 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1caa0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1cab0 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70  s NULL then no p
1cac0 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20  rogress.**      
1cad0 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69      handler is i
1cae0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1caf0 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72  12918} If the pr
1cb00 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1cb10 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1cb20 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74   other than 0, t
1cb30 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
1cb40 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1cb50 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e  a if [sqlite3_in
1cb60 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62  terrupt()] had b
1cb70 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20  een called..**  
1cb80 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e          <S30500>
1cb90 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1cba0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1cbb0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1cbc0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1cbd0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1cbe0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1cbf0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1cc00 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37  Connection {H127
1cc10 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  00} <S40200>.**.
1cc20 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cc30 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1cc40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
1cc50 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
1cc60 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
1cc70 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1cc80 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1cc90 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1cca0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1ccb0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1ccc0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1ccd0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1cce0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1ccf0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1cd00 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1cd10 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74  open16(). A [dat
1cd20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cd30 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1cd40 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1cd50 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1cd60 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1cd70 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1cd80 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1cd90 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1cda0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1cdb0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1cdc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1cdd0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1cde0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1cdf0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1ce00 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1ce10 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ce20 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20  ].** object. If 
1ce30 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1ce40 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1ce50 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1ce60 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1ce70 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1ce80 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1ce90 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1cea0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1ceb0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1cec0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1ced0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1cee0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1cef0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1cf00 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1cf10 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1cf20 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1cf30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
1cf40 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1cf50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1cf60 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1cf70 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cf80 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1cf90 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1cfa0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1cfb0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1cfc0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1cfd0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1cfe0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1cff0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1d000 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1d010 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1d020 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1d030 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1d040 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d050 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1d060 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1d070 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1d080 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1d090 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1d0a0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1d0b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d0c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1d0d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1d0e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1d0f0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1d100 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1d110 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1d120 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1d130 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1d140 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1d150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d160 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
1d170 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20  ameter can take 
1d180 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1d190 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1d1a0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1d1b0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1d1c0 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1d1d0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20  PEN_NOMUTEX] or 
1d1e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d1f0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a  LMUTEX] flags:.*
1d200 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1d210 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1d220 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1d230 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1d240 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1d250 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1d260 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1d270 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1d280 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1d290 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d2a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
1d2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d2c0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1d2d0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d2e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d2f0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d300 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1d310 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1d320 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1d330 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1d340 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1d350 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1d360 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1d370 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1d380 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1d390 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1d3a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1d3b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1d3c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1d3d0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1d3e0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1d3f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1d400 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1d410 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1d420 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1d430 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
1d440 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1d450 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1d460 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1d470 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1d480 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1d490 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1d4a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1d4b0 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  /dd>.** </dl>.**
1d4c0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1d4d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d4e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d4f0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1d500 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1d510 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1d520 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1d530 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1d540 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1d550 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1d560 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
1d570 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1d580 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a  LLMUTEX] flags,.
1d590 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d5a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d5b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1d5c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1d5d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d5e0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1d5f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d600 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1d610 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1d620 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1d630 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1d640 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1d650 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1d660 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d670 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1d680 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53  e.  If the.** [S
1d690 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d6a0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d6b0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1d6c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1d6d0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1d6e0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1d6f0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1d700 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1d710 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1d720 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1d730 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1d740 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  art-time..**.** 
1d750 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1d760 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1d770 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d780 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1d790 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1d7a0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1d7b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1d7c0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1d7d0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1d7e0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1d7f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d800 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1d810 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d820 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d830 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1d840 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1d850 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1d860 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1d870 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1d880 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1d890 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1d8a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1d8b0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1d8c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1d8d0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1d8e0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1d8f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1d900 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1d910 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1d920 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1d930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1d940 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1d950 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1d960 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d970 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1d980 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1d990 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
1d9a0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1d9b0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1d9c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1d9d0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1d9e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d9f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1da00 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
1da10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1da20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1da30 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1da40 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1da50 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1da60 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1da70 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1da80 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1da90 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1daa0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1dab0 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
1dac0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1dad0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1dae0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1daf0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1db00 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1db10 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1db20 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1db30 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1db40 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1db50 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1db60 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1db70 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1db80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1db90 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1dba0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1dbb0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1dbc0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1dbd0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1dbe0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1dbf0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1dc00 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1dc10 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1dc20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1dc30 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1dc40 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1dc50 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1dc60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dc70 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68  *.** {H12701} Th
1dc80 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1dc90 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1dca0 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
1dcb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dcc0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1dcd0 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20  rfaces create a 
1dce0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1dcf0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dd00 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
1dd10 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1dd20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66    the database f
1dd30 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
1dd40 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ir first paramet
1dd50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  er..**.** {H1270
1dd60 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  2} The filename 
1dd70 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1dd80 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1dd90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1dda0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1ddb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
1ddc0 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
1ddd0 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
1dde0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
1ddf0 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
1de00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1de10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ()]..**.** {H127
1de20 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
1de30 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1de40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1de50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1de60 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1de70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1de80 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
1de90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1dea0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1deb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dec0 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
1ded0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54  **.** {H12704} T
1dee0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1def0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1df00 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1df10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1df20 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1df30 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
1df40 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
1df50 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
1df60 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
1df70 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1df80 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
1df90 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54  **.** {H12706} T
1dfa0 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
1dfb0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
1dfc0 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
1dfd0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
1dfe0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1dff0 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
1e000 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
1e010 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
1e020 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20  ** {H12707} The 
1e030 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1e040 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1e050 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1e060 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1e070 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1e080 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
1e090 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  F-16..**.** {H12
1e0a0 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
1e0b0 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
1e0c0 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
1e0d0 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
1e0e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1e0f0 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
1e100 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
1e110 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
1e120 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
1e130 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
1e140 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d  ..**.** {H12711}
1e160 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e170 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e180 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e190 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e1a0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e1b0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e1c0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
1e1d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e1e0 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1e1f0 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
1e200 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  only..**.** {H12
1e210 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
1e220 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1e230 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1e240 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1e250 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1e260 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1e270 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e280 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e290 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1e2a0 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
1e2b0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1e2c0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
1e2d0 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
1e2e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e2f0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1e300 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1e310 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1e320 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d  ..**.** {H12713}
1e330 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e340 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e350 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e360 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
1e370 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e380 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1e390 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1e3a0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1e3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1e3c0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
1e3d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1e3e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ned..**.** {H127
1e3f0 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
1e400 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1e410 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1e420 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1e430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1e440 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1e450 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1e460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1e470 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1e480 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1e490 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
1e4a0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1e4b0 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
1e4c0 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
1e4d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
1e4e0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49  **.** {H12717} I
1e4f0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
1e500 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1e510 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1e520 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1e530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e540 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e550 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
1e560 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
1e570 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1e580 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
1e590 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
1e5a0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1e5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
1e5c0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e5d0 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e5e0 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e5f0 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e600 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e610 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e620 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e630 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74  ** {H12719} If t
1e640 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
1e650 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
1e660 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e670 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1e680 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e      ephemeral on
1e690 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1e6a0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a  ill be created..
1e6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1e6c0 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
1e6d0 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
1e6e0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
1e6f0 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
1e700 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
1e710 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
1e720 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54  **.** {H12721} T
1e730 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1e740 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64  nection] created
1e750 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   by [sqlite3_ope
1e760 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a  n_v2(F,D,G,V)].*
1e770 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
1e780 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1e790 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65  _vfs] object ide
1e7a0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56  ntified by the V
1e7b0 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20   parameter,.**  
1e7c0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64          or the d
1e7d0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1e7e0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56  vfs] object if V
1e7f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e800 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  er..**.** {H1272
1e810 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65  3} Two [database
1e820 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69   connections] wi
1e830 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f  ll share a commo
1e840 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20  n cache if both 
1e850 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  were.**         
1e860 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65   opened with the
1e870 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20   same VFS while 
1e880 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1e890 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20  de] was enabled 
1e8a0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1e8b0 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65  if both filename
1e8c0 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  s compare equal 
1e8d0 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61  using memcmp() a
1e8e0 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1e8f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f  .**          pro
1e900 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73  cessed by the [s
1e910 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75  qlite3_vfs | xFu
1e920 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68  llPathname] meth
1e930 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a  od of the VFS..*
1e940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1e950 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1e960 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e970 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e980 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1e990 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1e9a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1e9b0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1e9c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e9d0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1e9e0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1e9f0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ea00 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1ea10 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1ea20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1ea30 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1ea40 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1ea50 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1ea60 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1ea70 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1ea80 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1ea90 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1eaa0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1eab0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1eac0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ead0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1eaf0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1eb00 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1eb10 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1eb20 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1eb30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1eb40 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1eb50 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1eb60 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
1eb70 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
1eb80 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1eb90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1eba0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1ebb0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1ebc0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1ebd0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1ebe0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1ebf0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1ec00 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1ec10 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1ec20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ec30 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1ec40 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1ec50 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1ec60 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1ec70 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1ec80 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1ec90 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1eca0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1ecb0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78    The sqlite3_ex
1ecc0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1ecd0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1ece0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1ecf0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1ed00 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1ed10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ed20 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1ed30 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1ed40 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1ed50 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  sabled..**.** Th
1ed60 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1ed70 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1ed80 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1ed90 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1eda0 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1edb0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1edc0 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1edd0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1ede0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
1edf0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ee00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
1ee10 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
1ee20 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
1ee30 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1ee40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1ee50 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
1ee60 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
1ee70 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1ee80 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
1ee90 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
1eea0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
1eeb0 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
1eec0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
1eed0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
1eee0 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
1eef0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
1ef00 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1ef10 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
1ef20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
1ef30 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
1ef40 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
1ef50 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
1ef60 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
1ef70 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
1ef80 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
1ef90 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
1efa0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
1efb0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
1efc0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
1efd0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
1efe0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
1eff0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
1f000 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
1f010 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
1f020 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
1f030 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
1f040 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
1f050 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
1f060 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
1f070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f080 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
1f090 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1f0a0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
1f0b0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1f0c0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
1f0d0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
1f0e0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
1f0f0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
1f100 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
1f110 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
1f120 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
1f130 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
1f140 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
1f150 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
1f160 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
1f170 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
1f180 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
1f190 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
1f1a0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
1f1b0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
1f1c0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
1f1d0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
1f1e0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
1f1f0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
1f200 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
1f210 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  e set..**.** INV
1f220 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1f230 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c  H12801} The [sql
1f240 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d  ite3_errcode(D)]
1f250 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f260 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a  ns the numeric.*
1f270 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75  *          [resu
1f280 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
1f290 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1f2a0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1f2b0 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  recently.**     
1f2c0 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65       failed inte
1f2d0 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63  rface call assoc
1f2e0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1f2f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f300 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
1f310 31 32 38 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12802} The [sqli
1f320 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1f330 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61  code(D)] interfa
1f340 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1f350 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
1f360 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
1f370 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1f380 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a  e most recently.
1f390 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c  **          fail
1f3a0 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1f3b0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
1f3c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1f3d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
1f3e0 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68  *.** {H12803} Th
1f3f0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1f400 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  g(D)] and [sqlit
1f410 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a  e3_errmsg16(D)].
1f420 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1f430 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e  rfaces return En
1f440 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
1f450 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1f460 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1f470 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  he error in the 
1f480 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20  mostly recently 
1f490 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1f4a0 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20   call,.**       
1f4b0 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69     encoded as ei
1f4c0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1f4d0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1f4e0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37  y..**.** {H12807
1f4f0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1f500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f510 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
1f520 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f530 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
1f540 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
1f550 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
1f560 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
1f570 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d  ..**.** {H12808}
1f580 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
1f590 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
1f5a0 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
1f5b0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
1f5c0 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
1f5d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
1f5e0 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
1f5f0 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
1f600 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
1f610 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
1f620 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f630 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f640 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f650 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f660 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f670 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f680 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f690 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a  _errmsg16()]..**
1f6a0 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74  .** {H12809} Int
1f6b0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
1f6c0 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
1f6d0 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a  with a specific.
1f6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1f6f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f700 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20  ] (examples:.** 
1f710 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f720 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
1f730 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1f740 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a  shared_cache()].
1f750 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e  **          do n
1f760 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1f770 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1f780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f790 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f7a0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
1f7b0 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
1f7c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f7d0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1f7e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f7f0 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
1f800 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f810 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
1f820 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
1f830 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
1f840 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1f850 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1f860 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1f870 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f880 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1f890 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1f8a0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1f8b0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
1f8c0 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
1f8d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1f8e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1f8f0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f900 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1f910 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1f920 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1f930 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1f940 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1f950 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1f960 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1f970 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1f980 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1f990 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1f9a0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1f9b0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1f9c0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1f9d0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1f9e0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1f9f0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1fa00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1fa10 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1fa20 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1fa30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fa40 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1fa50 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1fa60 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1fa70 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1fa80 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1fa90 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1faa0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1fab0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1fac0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1fad0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1fae0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1faf0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1fb00 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1fb10 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1fb20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fb30 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1fb40 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1fb50 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1fb60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1fb70 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1fb80 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1fb90 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1fba0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1fbb0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1fbc0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1fbd0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1fbe0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1fbf0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fc00 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1fc10 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1fc20 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1fc30 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1fc40 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1fc50 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
1fc60 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
1fc70 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1fc80 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1fc90 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1fca0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1fcb0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1fcc0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1fcd0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1fce0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1fcf0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1fd00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1fd10 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1fd20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1fd30 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1fd40 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1fd50 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1fd60 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1fd70 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1fd80 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1fd90 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1fda0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1fdb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fdc0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1fdd0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1fde0 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1fdf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
1fe00 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
1fe10 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1fe20 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1fe30 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1fe40 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1fe50 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1fe60 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1fe70 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1fe80 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72   is a hard upper
1fe90 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79  .** bound set by
1fea0 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
1feb0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1fec0 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54  acro named SQLIT
1fed0 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54  E_MAX_XYZ..** (T
1fee0 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1fef0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1ff00 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1ff10 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
1ff20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1ff30 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1ff40 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1ff50 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1ff60 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1ff70 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
1ff80 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
1ff90 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1ffa0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1ffb0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1ffc0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1ffd0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1ffe0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1fff0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
20000 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
20010 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
20020 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
20030 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
20040 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
20050 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77   be a.** webbrow
20060 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
20070 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
20080 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
20090 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
200a0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
200b0 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
200c0 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
200d0 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
200e0 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
200f0 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
20100 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
20110 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
20120 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
20130 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
20140 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
20150 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
20160 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
20170 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
20180 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
20190 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
201a0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
201b0 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
201c0 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
201d0 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
201e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
201f0 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
20200 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
20210 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
20220 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
20230 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
20240 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
20250 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
20260 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
20270 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
20280 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20290 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
202a0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
202b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
202c0 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
202d0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
202e0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
202f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20  .**.** {H12762} 
20300 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
20310 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
20320 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
20330 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
20340 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
20350 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
20360 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
20370 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
20380 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
20390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
203a0 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
203b0 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
203c0 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
203d0 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
203e0 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
203f0 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
20400 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
20410 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {H12766} A succe
20420 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
20430 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
20440 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
20450 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
20460 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
20470 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
20480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20490 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
204a0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41  **.** {H12769} A
204b0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
204c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
204d0 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
204e0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
204f0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
20500 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
20510 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
20520 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
20530 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
20540 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
20550 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
20560 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
20570 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
20580 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
20590 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
205a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
205b0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
205c0 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d  egories {H12790}
205d0 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59   <H12760>.** KEY
205e0 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
205f0 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
20600 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
20610 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
20620 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
20630 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
20640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20650 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
20660 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
20670 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
20680 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
20690 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
206a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
206b0 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
206c0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
206d0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
206e0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
206f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20700 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
20710 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
20720 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
20730 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20740 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
20750 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
20760 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
20770 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
20780 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
20790 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
207a0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
207b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
207c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
207d0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
207e0 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
207f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
20800 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f  et of a SELECT o
20810 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
20820 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
20830 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
20840 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
20850 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
20860 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
20870 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20880 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
20890 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
208a0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
208b0 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
208c0 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
208d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
208e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
208f0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
20900 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20910 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
20920 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
20930 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
20940 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
20950 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
20960 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
20970 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
20980 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
20990 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
209a0 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
209b0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
209c0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
209d0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
209e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
209f0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
20a00 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
20a10 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20a20 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
20a30 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
20a40 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20a50 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
20a60 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
20a70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20a80 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61  r of attached da
20a90 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  tabases.</dd>.**
20aa0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20ab0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
20ac0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
20ad0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20ae0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
20af0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
20b00 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a  to the LIKE or.*
20b10 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73  * GLOB operators
20b20 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
20b30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
20b40 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
20b50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20b60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20b70 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20  variables in an 
20b80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
20b90 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75  at can.** be bou
20ba0 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  nd.</dd>.** </dl
20bb0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
20bc0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
20bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20be0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
20bf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
20c00 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20c10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
20c20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20c30 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
20c40 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
20c50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20c60 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
20c70 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
20c80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20c90 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
20ca0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
20cb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
20cc0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
20cd0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
20ce0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20cf0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
20d00 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
20d10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20d20 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
20d30 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
20d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20d50 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
20d60 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
20d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20d80 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20d90 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a  ER           9..
20da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20db0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
20dc0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30   Statement {H130
20dd0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20  10} <S10000>.** 
20de0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
20df0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
20e00 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
20e10 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
20e20 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
20e30 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
20e40 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
20e50 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
20e60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
20e70 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
20e80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
20e90 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
20ea0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20eb0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
20ec0 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  ** prior call to
20ed0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
20ee0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
20ef0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
20f00 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
20f10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
20f20 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
20f30 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
20f40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
20f50 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
20f60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
20f70 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
20f80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
20f90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
20fa0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
20fb0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
20fc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
20fd0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
20fe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20ff0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
21000 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
21010 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
21020 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
21030 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
21040 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
21050 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
21060 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
21070 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21080 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
21090 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
210a0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
210b0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
210c0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
210d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
210e0 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
210f0 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
21100 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
21110 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
21120 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
21130 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
21140 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
21150 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
21160 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
21170 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
21180 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
21190 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
211a0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
211b0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
211c0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
211d0 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
211e0 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
211f0 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
21200 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
21210 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
21220 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
21230 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
21240 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
21250 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
21260 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
21270 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
21280 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21290 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
212a0 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
212b0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
212c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
212d0 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
212e0 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
212f0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
21300 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
21310 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
21320 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
21330 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
21340 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
21350 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
21360 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
21370 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
21380 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
21390 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
213a0 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
213b0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
213c0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
213d0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
213e0 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
213f0 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
21400 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
21410 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
21420 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
21430 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
21440 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
21450 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {A13018} The cal
21460 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
21470 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
21480 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
21490 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
214a0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
214b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
214c0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
214d0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
214e0 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
214f0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
21500 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74   is returned, ot
21510 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
21520 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
21530 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
21540 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21550 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
21560 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
21570 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
21580 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
21590 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
215a0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
215b0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
215c0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
215d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
215e0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
215f0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
21600 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
21610 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
21620 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
21630 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
21640 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
21650 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
21660 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
21670 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
21680 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
21690 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
216a0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
216b0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
216c0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
216d0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
216e0 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
216f0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
21700 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
21710 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
21720 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
21730 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
21740 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
21750 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
21760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21770 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
21780 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
21790 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
217a0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
217b0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
217c0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
217d0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
217e0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
217f0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
21800 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
21810 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
21820 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
21830 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
21840 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
21850 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
21860 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
21870 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
21880 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
21890 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
218a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
218b0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
218c0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
218d0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
218e0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
218f0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
21900 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
21910 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
21920 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
21930 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
21940 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
21950 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
21960 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
21970 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
21980 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
21990 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
219a0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
219b0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
219c0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
219d0 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20  s].  The legacy 
219e0 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
219f0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
21a00 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
21a10 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
21a20 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
21a30 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
21a40 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
21a50 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
21a60 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
21a70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
21a80 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e   order.** to fin
21a90 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
21aa0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
21ab0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
21ac0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
21ad0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
21ae0 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
21af0 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
21b00 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
21b10 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
21b20 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
21b30 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21b40 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20  ** {H13011} The 
21b50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b60 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
21b70 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
21b80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21b90 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
21ba0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
21bb0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
21bc0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
21bd0 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
21be0 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
21bf0 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20  ** {H13012} The 
21c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21c10 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
21c20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
21c30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21c40 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
21c50 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
21c60 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
21c70 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
21c80 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
21c90 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
21ca0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21cb0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21cc0 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65   {H13013} If the
21cd0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
21ce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
21cf0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
21d00 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
21d10 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
21d20 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
21d30 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53  than zero, the S
21d40 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20  QL text is.**   
21d50 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d         read from
21d60 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
21d70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
21d80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
21d90 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66  *.** {H13014} If
21da0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
21db0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
21dc0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
21dd0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
21de0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
21df0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e  ts variants is n
21e00 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
21e10 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73  n at most nBytes
21e20 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
21e30 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69        SQL text i
21e40 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
21e50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d  ..**.** {H13015}
21e60 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   In [sqlite3_pre
21e70 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21e80 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64  N,P,pzTail)] and
21e90 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
21ea0 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
21eb0 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74   zSql input text
21ec0 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74   contains more t
21ed0 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74  han one SQL stat
21ee0 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ement.**        
21ef0 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20    and pzTail is 
21f00 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a  not NULL, then *
21f10 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
21f20 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a  o point to the.*
21f30 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
21f40 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
21f50 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
21f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
21f70 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20   zSql..**       
21f80 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f     <todo>What do
21f90 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74  es *pzTail point
21fa0 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20   to if there is 
21fb0 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f  one statement?</
21fc0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  todo>.**.** {H13
21fd0 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  016} A successfu
21fe0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
21ff0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
22000 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e  ,zSql,N,ppStmt,.
22010 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
22020 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
22030 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69  ariants writes i
22040 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f  nto *ppStmt a po
22050 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
22060 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
22070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22080 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
22090 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e  NULL if zSql con
220a0 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
220b0 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20    nothing other 
220c0 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20  than whitespace 
220d0 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a  or comments..**.
220e0 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20  ** {H13019} The 
220f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22100 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
22110 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
22120 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
22130 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
22140 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
22150 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
22160 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
22170 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66  .** {H13021} Bef
22180 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
22190 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
221a0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
221b0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
221c0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
221d0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
221e0 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
221f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
22200 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ]),.**          
22210 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a  they first set *
22220 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
22230 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
22240 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
22250 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22260 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22270 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22280 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
22290 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
222a0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
222b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
222c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
222d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
222e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
222f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
22300 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22310 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22320 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22330 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
22340 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
22350 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
22360 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
22370 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
22380 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
22390 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
223a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
223b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
223c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
223d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
223e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
223f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
22400 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
22410 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
22420 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
22430 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
22440 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
22450 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
22460 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
22470 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
22480 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
22490 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
224a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
224b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
224c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
224d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
224e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
224f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22500 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22510 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22530 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
22540 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
22550 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
22560 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
22570 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
22580 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22590 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
225a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
225b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
225c0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
225d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
225e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
225f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
22610 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
22620 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
22630 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
22640 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
22650 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
22660 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
22670 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
22680 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22690 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
226a0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
226b0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
226c0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
226d0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
226e0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
226f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22700 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
22710 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
22720 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
22730 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
22740 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
22750 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
22760 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
22770 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
22780 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
22790 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
227a0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
227b0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
227c0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
227d0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
227e0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
227f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22800 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
22810 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
22820 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
22830 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22840 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
22850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22860 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
22870 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
22880 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
22890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
228a0 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
228b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
228c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
228d0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
228e0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
228f0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
22900 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
22910 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22920 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22930 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
22940 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
22950 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
22960 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
22970 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
22980 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
22990 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
229a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
229b0 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
229c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
229d0 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {H13102} If the 
229e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
229f0 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
22a00 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
22a10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22a20 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
22a30 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
22a40 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
22a50 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
22a60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22a70 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
22a80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
22a90 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
22aa0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
22ab0 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73  * {H13103} The s
22ac0 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
22ad0 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
22ae0 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
22af0 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
22b00 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22b10 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
22b20 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
22b30 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
22b40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22b50 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
22b60 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22b70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22b80 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
22b90 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
22ba0 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
22bb0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
22bc0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
22bd0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
22be0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22bf0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
22c00 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
22c10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22c20 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
22c30 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
22c40 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
22c50 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
22c60 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
22c70 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
22c80 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
22c90 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
22ca0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
22cb0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22cc0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
22cd0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
22ce0 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
22cf0 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
22d00 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
22d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22d20 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
22d30 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
22d40 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
22d50 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
22d60 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
22d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22d80 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
22d90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
22da0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
22db0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
22dc0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
22dd0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
22de0 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
22df0 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
22e00 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
22e10 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
22e20 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
22e30 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
22e40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22e50 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
22e60 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
22e70 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
22e80 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
22e90 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
22ea0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
22eb0 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
22ec0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
22ed0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
22ee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22ef0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
22f00 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
22f10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
22f20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22f30 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
22f40 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
22f50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
22f60 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
22f70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
22f80 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
22f90 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
22fa0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
22fb0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
22fc0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
22fd0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
22fe0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
22ff0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
23000 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
23010 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
23020 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
23030 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
23040 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
23050 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
23060 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
23070 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
23080 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
23090 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
230a0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
230b0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
230c0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
230d0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
230e0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
230f0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
23100 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
23110 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
23120 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
23130 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
23140 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23150 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
23160 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
23170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
23180 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23190 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
231a0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
231b0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
231c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
231d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
231e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
231f0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
23200 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
23210 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
23220 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
23230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
23240 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
23250 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
23260 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23270 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
23280 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
23290 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
232a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
232b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
232c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
232d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
232e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
232f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
23300 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
23310 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
23320 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23330 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
23340 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
23350 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
23360 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
23370 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
23380 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
23390 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
233a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
233b0 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
233c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
233d0 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
233e0 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
233f0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
23400 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
23410 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
23420 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
23430 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
23440 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
23450 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23460 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
23470 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
23480 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23490 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
234a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
234b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
234c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
234d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
234e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
234f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
23500 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
23510 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
23520 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
23530 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
23540 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
23550 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
23560 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
23570 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
23580 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
23590 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
235a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
235b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
235c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
235d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
235e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
235f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
23600 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
23610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
23620 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
23630 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
23640 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23650 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
23660 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
23670 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
23680 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
23690 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
236a0 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
236b0 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
236c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
236d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
236e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
236f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
23700 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
23710 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
23720 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
23730 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
23740 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
23750 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
23760 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
23770 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
23780 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
23790 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
237a0 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
237b0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
237c0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
237d0 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
237e0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
237f0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
23800 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
23810 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
23820 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
23830 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
23840 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
23850 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
23860 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23870 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
23880 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
23890 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
238a0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
238b0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
238c0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
238d0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
238e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
238f0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
23900 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
23910 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23920 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
23930 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
23940 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
23950 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
23960 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
23970 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
23980 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
23990 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
239a0 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
239b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
239c0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
239d0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
239e0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
239f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
23a00 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
23a10 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
23a20 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
23a30 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
23a40 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
23a50 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
23a60 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
23a70 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
23a80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23a90 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
23aa0 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
23ab0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
23ac0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
23ad0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
23ae0 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
23af0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
23b00 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
23b10 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23b20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
23b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23b40 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
23b50 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
23b60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
23b70 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
23b80 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
23b90 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
23ba0 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
23bb0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
23bc0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
23bd0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
23be0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
23bf0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23c00 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
23c10 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
23c20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
23c30 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
23c40 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
23c50 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
23c60 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23c70 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
23c80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
23c90 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
23ca0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
23cb0 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
23cc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
23cd0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
23ce0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
23cf0 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
23d00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23d10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
23d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23d30 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
23d40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
23d50 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
23d60 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
23d70 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
23d80 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
23d90 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
23da0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
23db0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23dc0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
23dd0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
23de0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
23df0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
23e00 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
23e10 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
23e20 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
23e30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
23e40 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
23e50 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
23e60 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
23e70 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
23e80 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
23e90 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
23ea0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
23eb0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
23ec0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
23ed0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
23ee0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23ef0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
23f00 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
23f10 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
23f20 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
23f30 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
23f40 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
23f50 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
23f60 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
23f70 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
23f80 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
23f90 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
23fa0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
23fb0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
23fc0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
23fd0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
23fe0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
23ff0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
24000 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
24010 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
24020 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
24030 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
24040 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
24050 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
24060 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
24070 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
24080 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
24090 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
240a0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
240b0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
240c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
240d0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
240e0 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
240f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24100 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
24110 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
24120 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
24130 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
24140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
24150 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
24160 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
24170 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
24180 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
24190 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
241a0 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
241b0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
241c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
241d0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
241e0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
241f0 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
24200 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
24210 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
24220 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
24230 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
24240 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
24250 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
24260 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
24270 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
24280 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
24290 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
242a0 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
242b0 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
242c0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
242d0 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
242e0 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
242f0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
24300 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
24310 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
24320 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
24330 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
24340 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
24350 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
24360 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
24370 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
24380 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
24390 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
243a0 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
243b0 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
243c0 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
243d0 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
243e0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
243f0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
24400 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
24410 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
24420 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
24430 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
24440 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
24450 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
24460 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24470 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
24480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24490 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
244a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
244b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36  S:.**.** {H13506
244c0 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
244d0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72  ment compiler] r
244e0 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73  ecognizes tokens
244f0 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a   of the forms.**
24500 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22            "?", "
24510 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22  ?NNN", "$VVV", "
24520 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56  :VVV", and "@VVV
24530 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74  " as SQL paramet
24540 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ers,.**         
24550 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e   where NNN is an
24560 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
24570 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73  e or more digits
24580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
24590 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e   where VVV is an
245a0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
245b0 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e  e or more alphan
245c0 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
245d0 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72     characters or
245e0 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79   "::" optionally
245f0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73   followed by a s
24600 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
24610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
24620 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61  spaces and conta
24630 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65  ined within pare
24640 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ntheses..**.** {
24650 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74  H13509} The init
24660 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ial value of an 
24670 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
24680 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
24690 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20  3512} The index 
246a0 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61  of an "?" SQL pa
246b0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c  rameter is one l
246c0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a  arger than the.*
246d0 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65  *          large
246e0 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  st index of SQL 
246f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24700 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a   left, or 1 if.*
24710 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22  *          the "
24720 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  ?" is the leftmo
24730 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
24740 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d  ..**.** {H13515}
24750 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
24760 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61   "?NNN" SQL para
24770 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74  meter is the int
24780 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20  eger NNN..**.** 
24790 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64  {H13518} The ind
247a0 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c  ex of an ":VVV",
247b0 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56   "$VVV", or "@VV
247c0 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  V" SQL parameter
247d0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
247e0 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
247f0 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73  index of leftmos
24800 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66  t occurrences of
24810 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
24820 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
24830 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61   or one more tha
24840 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e  n the largest in
24850 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20  dex over all.** 
24860 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
24870 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20  ers to the left 
24880 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66  if this is the f
24890 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a  irst occurrence.
248a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
248b0 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  his parameter, o
248c0 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74  r 1 if this is t
248d0 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61  he leftmost para
248e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
248f0 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73  3521} The [SQL s
24900 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
24910 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  r] fails with an
24920 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a   [SQLITE_RANGE].
24930 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
24940 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f  r if the index o
24950 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
24960 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
24970 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  1.**          or
24980 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
24990 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53  e compile-time S
249a0 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
249b0 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20  LE_NUMBER.**    
249c0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e        parameter.
249d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20  .**.** {H13524} 
249e0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
249f0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24a00 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56  lite3_bind(S,N,V
24a10 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
24a20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65     associate the
24a30 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c   value V with al
24a40 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
24a50 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20   having an.**   
24a60 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20         index of 
24a70 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  N in the [prepar
24a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
24a90 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20  .**.** {H13527} 
24aa0 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
24ab0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24ac0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e  lite3_bind(S,N,.
24ad0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
24ae0 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
24af0 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73  calls with the s
24b00 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20  ame values of S 
24b10 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and N..**.** {H1
24b20 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65  3530} Bindings e
24b30 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73  stablished by [s
24b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24b50 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24b60 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  S,...)].**      
24b70 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f      persist acro
24b80 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ss calls to [sql
24b90 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a  ite3_reset(S)]..
24ba0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49  **.** {H13533} I
24bb0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
24bc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
24bd0 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
24be0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24bf0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
24c00 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
24c10 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24c20 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24c30 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24c40 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a  nds the first L.
24c50 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65  **          byte
24c60 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  s of the BLOB or
24c70 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
24c80 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a  to by V, when L.
24c90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
24ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
24cb0 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63  ** {H13536} In c
24cc0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24cd0 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
24ce0 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ,L,D)] or.**    
24cf0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24d00 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24d10 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24d20 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a  nds characters.*
24d30 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
24d40 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  V through the fi
24d50 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
24d60 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67  er when L is neg
24d70 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
24d80 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3539} In calls t
24d90 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24da0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
24db0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
24dc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24dd0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
24de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24e00 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
24e10 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
24e20 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
24e30 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
24e40 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65  _STATIC], SQLite
24e50 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
24e60 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20  e value V.**    
24e70 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e        is held in
24e80 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65   static unmanage
24e90 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c  d space that wil
24ea0 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  l not change.** 
24eb0 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20           during 
24ec0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
24ed0 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a  the binding..**.
24ee0 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63  ** {H13542} In c
24ef0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24f00 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
24f10 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
24f20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24f30 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
24f40 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
24f50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24f60 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24f70 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
24f80 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
24f90 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
24fa0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
24fb0 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d  ], the routine m
24fc0 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  akes a.**       
24fd0 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
24fe0 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62  of the value V b
24ff0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
25000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d  ..**.** {H13545}
25010 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
25020 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
25030 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
25040 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
25050 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
25060 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
25070 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25080 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
25090 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
250a0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
250b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
250c0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
250d0 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
250e0 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
250f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25100 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74  value V after it
25110 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
25120 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e  ing the value V.
25130 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20  .**.** {H13548} 
25140 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
25150 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
25160 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
25170 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
25180 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c           is a BL
25190 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  OB of L bytes, o
251a0 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
251b0 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67  BLOB if L is neg
251c0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
251d0 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
251e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
251f0 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
25200 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
25210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
25220 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
25230 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25240 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
25250 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
25260 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25270 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
25280 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25290 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
252a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
252b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
252c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
252d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
252e0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
252f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
25300 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
25310 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
25320 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25330 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
25340 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
25350 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25360 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
25370 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25380 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
25390 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
253a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
253b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
253c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
253d0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
253e0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
253f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25400 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25410 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
25420 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
25430 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
25440 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
25450 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25460 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
25470 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
25480 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
25490 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
254a0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
254b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
254c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
254d0 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
254e0 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
254f0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
25500 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25510 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
25520 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
25530 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
25540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25550 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
25560 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
25570 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
25580 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
25590 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
255a0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
255b0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
255c0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
255d0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
255e0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
255f0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
25600 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
25610 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
25620 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
25630 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
25640 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
25650 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
25660 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
25670 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
25680 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
25690 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
256a0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
256b0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
256c0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
256d0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
256e0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
256f0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
25700 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
25710 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25720 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25730 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
25740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25750 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25760 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25770 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25780 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25790 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
257a0 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68  *.** {H13601} Th
257b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
257c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
257d0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
257e0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
257f0 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
25800 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
25810 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
25820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
25830 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25840 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63  ] S, or 0 if S c
25850 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
25860 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
25870 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
25880 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
25890 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
258a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
258b0 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
258c0 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
258d0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
258e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
258f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25900 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
25910 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
25920 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
25930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25940 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
25950 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
25960 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
25970 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
25980 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
25990 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
259a0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
259b0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
259c0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
259d0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
259e0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
259f0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
25a00 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
25a10 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
25a20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
25a30 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
25a40 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
25a50 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
25a60 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
25a70 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
25a80 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
25a90 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
25aa0 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
25ab0 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
25ac0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
25ad0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
25ae0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
25af0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
25b00 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
25b10 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
25b20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
25b30 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
25b40 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
25b50 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
25b60 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
25b70 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
25b80 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
25b90 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
25ba0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
25bb0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
25bc0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
25bd0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
25be0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
25bf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25c00 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
25c10 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25c30 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
25c40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25c50 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
25c60 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
25c70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25c80 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
25c90 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
25ca0 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20  ** {H13621} The 
25cb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25cc0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
25cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
25ce0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
25cf0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
25d00 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
25d10 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
25d20 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
25d30 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
25d40 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
25d50 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
25d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
25d70 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
25d80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
25d90 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
25da0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
25db0 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
25dc0 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
25dd0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
25de0 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74  er "?"..*/.const
25df0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
25e00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
25e10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
25e20 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
25e30 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
25e40 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
25e50 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
25e60 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
25e70 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
25e80 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25e90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25ea0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
25eb0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
25ec0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
25ed0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
25ee0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
25ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25f00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25f10 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
25f20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
25f30 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
25f40 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
25f50 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
25f60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
25f70 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
25f80 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
25f90 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
25fa0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
25fb0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
25fc0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
25fd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25fe0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
25ff0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
26000 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
26010 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
26020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26030 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
26040 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
26050 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26060 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
26070 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
26080 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b  * {H13641} The [
26090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
260a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
260b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
260c0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
260d0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
260e0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  L parameter in t
260f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26100 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
26110 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
26120 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
26130 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
26140 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
26150 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
26160 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
26170 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26180 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
26190 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
261a0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
261b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
261c0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
261d0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
261e0 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20  tement {H13660} 
261f0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S70300>.**.** C
26200 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
26210 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
26220 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
26230 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
26240 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
26250 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
26260 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
26270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26280 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
26290 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
262a0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
262b0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
262c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
262d0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54  **.** {H13661} T
262e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
262f0 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
26300 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
26310 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  all SQL.**      
26320 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69      parameter bi
26330 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70  ndings in the [p
26340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26350 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c  t] S back to NUL
26360 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
26370 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
26380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
26390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
263a0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
263b0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
263c0 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
263d0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
263e0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
263f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
26400 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
26410 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
26420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26430 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
26440 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
26450 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
26460 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
26470 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
26480 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
26490 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
264a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
264b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d  :.**.** {H13711}
264c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
264d0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
264e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
264f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
26500 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
26510 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
26520 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
26530 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
26540 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
26550 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
26560 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
26570 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
26580 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
26590 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
265a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
265b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
265c0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
265d0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
265e0 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
265f0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
26600 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26610 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
26620 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
26630 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
26640 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26650 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26660 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
26670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26680 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
26690 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
266a0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
266b0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
266c0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
266d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
266e0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
266f0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
26700 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
26710 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
26720 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26730 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
26740 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
26750 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
26760 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
26770 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
26780 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26790 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
267a0 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
267b0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
267c0 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
267d0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
267e0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
267f0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
26800 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26810 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
26820 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
26830 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26840 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
26850 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
26860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26870 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
26880 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
26890 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
268a0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
268b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
268c0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
268d0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
268e0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
268f0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
26900 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
26910 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
26920 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
26930 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
26940 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
26950 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
26960 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
26970 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
26980 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
26990 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
269a0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
269b0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
269c0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
269d0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
269e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
269f0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
26a00 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
26a10 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
26a20 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
26a30 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
26a40 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26a50 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73  .** {H13721} A s
26a60 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
26a70 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
26a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26a90 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
26aa0 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
26ab0 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
26ac0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26ad0 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
26ae0 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
26af0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
26b00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26b10 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
26b20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26b30 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
26b40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26b50 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
26b60 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75  ** {H13723} A su
26b70 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
26b80 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
26b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26ba0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
26bb0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
26bc0 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
26bd0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
26be0 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
26bf0 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
26c00 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
26c10 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
26c20 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
26c30 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
26c40 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
26c50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
26c60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
26c70 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
26c80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26c90 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
26ca0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
26cb0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61  column_name()] a
26cc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26cd0 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20  mn_name16()].** 
26ce0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
26cf0 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
26d00 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65  L pointer if the
26d10 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a  y are unable to.
26d20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
26d30 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
26d40 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c  old their normal
26d50 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
26d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20  .**.** {H13725} 
26d70 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
26d80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
26d90 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
26da0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
26db0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26dc0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
26dd0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
26de0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
26df0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
26e00 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
26e10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ter..**.** {H137
26e20 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
26e30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
26e40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26e50 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
26e60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26e70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
26e80 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
26e90 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
26ea0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
26eb0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
26ec0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
26ed0 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
26ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
26ef0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
26f00 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
26f10 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alled..**.** {H1
26f20 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
26f30 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
26f40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26f50 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
26f60 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
26f70 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
26f80 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
26f90 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
26fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
26fb0 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
26fc0 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
26fd0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
26ff0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27000 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
27010 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27020 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
27030 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
27040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27050 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
27060 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
27070 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
27080 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
27090 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
270a0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
270b0 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
270c0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
270d0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
270e0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
270f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
27100 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
27110 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
27120 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
27130 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
27140 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
27150 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
27160 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
27170 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
27180 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
27190 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
271a0 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
271b0 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
271c0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
271d0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
271e0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
271f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
27200 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
27210 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
27220 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
27230 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
27240 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
27250 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
27260 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27270 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
27280 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
27290 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
272a0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
272b0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
272c0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
272d0 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
272e0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
272f0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27300 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27310 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
27320 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
27330 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
27340 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
27350 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
27360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
27370 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
27380 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
27390 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
273a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
273b0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
273c0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
273d0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
273e0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
273f0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
27400 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
27410 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
27420 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
27430 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
27440 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
27450 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
27460 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
27470 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
27480 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
27490 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
274a0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
274b0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
274c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
274d0 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
274e0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
274f0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
27500 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
27510 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
27520 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
27530 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
27540 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
27550 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
27560 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
27570 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
27580 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
27590 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
275a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
275b0 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
275c0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
275d0 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
275e0 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
275f0 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
27600 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
27610 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
27620 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
27630 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
27640 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
27650 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
27660 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
27670 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
27680 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
27690 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
276a0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
276b0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
276c0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
276d0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
276e0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
276f0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
27700 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
27710 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27720 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
27730 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65  .** {H13741} The
27740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27750 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
27760 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27770 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27780 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27790 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
277a0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
277b0 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
277c0 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
277d0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
277e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
277f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27800 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
27810 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27820 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27830 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27840 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27850 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27860 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27870 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27880 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27890 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
278a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
278b0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
278c0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
278d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
278e0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
278f0 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
27900 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
27910 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27920 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
27930 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
27940 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
27950 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27960 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27970 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27980 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27990 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
279a0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
279b0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
279c0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
279d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
279e0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
279f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27a00 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27a10 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68  *.** {H13743} Th
27a20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27a30 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
27a40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27a50 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27a60 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27a70 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
27a80 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27a90 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
27aa0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
27ab0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27ac0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27ad0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27ae0 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27af0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27b00 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27b10 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27b20 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27b30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27b40 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27b50 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27b60 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27b70 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68  *.** {H13744} Th
27b80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27b90 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
27ba0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27bb0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27bc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27bd0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
27be0 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
27bf0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27c00 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
27c10 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
27c20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27c30 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27c50 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
27c60 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
27c70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27c80 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27c90 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27ca0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27cb0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27cc0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27cd0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27ce0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27cf0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
27d00 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
27d10 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
27d20 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
27d30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
27d40 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
27d50 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
27d60 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
27d70 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
27d80 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
27d90 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
27da0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27db0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
27dc0 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
27dd0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
27de0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27df0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
27e00 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
27e10 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
27e20 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
27e30 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
27e40 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
27e50 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b  * {H13746} The [
27e60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
27e70 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
27e80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27e90 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27ea0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27eb0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
27ec0 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
27ed0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
27ee0 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
27ef0 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77     column from w
27f00 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
27f10 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27f20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
27f30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27f40 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
27f50 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27f60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e Nth column.** 
27f70 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73           of S is
27f80 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
27f90 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
27fa0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27fb0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
27fc0 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
27fd0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
27fe0 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
27ff0 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
28000 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
28010 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
28020 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
28030 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
28040 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
28050 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65  re valid for the
28060 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
28070 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28080 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
28090 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65    or until the e
280a0 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67  ncoding is chang
280b0 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65  ed by another me
280c0 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
280d0 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c     interface cal
280e0 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70  l for the same p
280f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28100 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  t and column..**
28110 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
28120 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20  .**.** {A13751} 
28130 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
28140 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
28150 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
28160 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
28170 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
28180 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
28190 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
281a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
281b0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
281c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
281d0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
281e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
281f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28200 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28210 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
28220 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
28240 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
28250 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28260 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28270 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
28280 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28290 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
282a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
282b0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
282c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
282d0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
282e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
282f0 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
28300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28310 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28320 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
28330 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
28340 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28350 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28360 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
28370 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
28380 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28390 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
283a0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
283b0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
283c0 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e  H13760} <S10700>
283d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
283e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
283f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28400 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
28410 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
28420 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28430 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
28440 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
28450 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
28460 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
28470 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
28480 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
28490 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
284a0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
284b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
284c0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
284d0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
284e0 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
284f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
28500 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
28510 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
28520 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
28530 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
28540 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
28550 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
28560 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
28570 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44  -8 encoded. {END
28580 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  }.**.** For exam
28590 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
285a0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
285b0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
285c0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
285d0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
285e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
285f0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
28600 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
28610 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
28620 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
28630 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
28640 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
28650 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
28660 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
28670 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
28680 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
28690 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
286a0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
286b0 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  n (i==0)..**.** 
286c0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
286d0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
286e0 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
286f0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
28700 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
28710 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
28720 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
28730 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
28740 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
28750 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
28760 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
28770 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
28780 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
28790 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
287a0 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
287b0 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
287c0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
287d0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
287e0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
287f0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
28800 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
28810 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
28820 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
28830 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36  TS:.**.** {H1376
28840 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  1}  A successful
28850 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28860 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28870 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  e(S,N)] returns 
28880 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a  a.**           z
28890 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
288a0 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  TF-8 string cont
288b0 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
288c0 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20  red datatype.** 
288d0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
288e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
288f0 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68  at appears as th
28900 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
28910 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  mbered.**       
28920 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74      from 0) of t
28930 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
28940 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28950 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
28960 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73  ** {H13762}  A s
28970 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
28980 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
28990 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
289a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
289b0 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
289c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
289d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
289e0 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
289f0 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
28a00 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
28a10 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
28a20 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
28a30 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
28a40 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
28a50 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
28a60 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
28a70 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
28a80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
28a90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28aa0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
28ab0 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
28ac0 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
28ad0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
28ae0 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
28af0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
28b00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28b10 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
28b20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
28b30 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
28b40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28b50 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
28b60 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28b70 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
28b80 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
28b90 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69  ble column, or i
28ba0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28bb0 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
28bc0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
28bd0 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
28be0 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
28bf0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
28c00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28c10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28c20 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
28c30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
28c40 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28c50 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
28c60 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
28c70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
28c80 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
28c90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28ca0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28cc0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
28cd0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
28cf0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
28d00 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
28d10 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
28d20 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
28d30 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
28d40 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
28d50 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
28d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28d70 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28d80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28d90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
28da0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28db0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
28dc0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
28dd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28de0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
28df0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
28e00 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
28e10 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
28e20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
28e30 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
28e40 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
28e50 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28e60 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
28e70 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
28e80 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
28e90 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
28ea0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
28eb0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
28ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28ed0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
28ee0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28ef0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
28f00 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
28f10 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
28f20 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
28f30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28f40 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
28f50 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
28f60 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
28f70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
28f80 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
28f90 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
28fa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
28fb0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
28fc0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
28fd0 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
28fe0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
28ff0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
29000 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
29010 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
29020 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
29030 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
29040 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
29050 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
29060 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
29070 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
29080 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
29090 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
290a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
290b0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
290c0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
290d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
290e0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
290f0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
29100 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
29110 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
29120 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
29130 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
29140 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
29150 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
29160 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
29170 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
29180 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
29190 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
291a0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
291b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
291c0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
291d0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
291e0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
291f0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
29200 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
29210 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
29220 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
29230 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
29240 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
29250 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
29260 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29270 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
29280 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
29290 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
292a0 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
292b0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
292c0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
292d0 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
292e0 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
292f0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
29300 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29310 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
29320 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
29330 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
29340 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
29350 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
29360 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
29370 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
29380 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29390 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
293a0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
293b0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
293c0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
293d0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
293e0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
293f0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
29400 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29410 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
29430 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29440 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
29450 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
29460 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
29470 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
29480 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
29490 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
294a0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
294b0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
294c0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
294d0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
294e0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
294f0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29500 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
29510 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
29520 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
29530 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
29540 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
29550 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
29560 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
29570 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29580 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29590 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
295a0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
295b0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
295c0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
295d0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
295e0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
295f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29600 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
29610 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29620 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
29630 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
29640 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
29650 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
29660 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
29670 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
29680 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
29690 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
296a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
296b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
296c0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
296d0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
296e0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
296f0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
29700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29710 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
29720 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
29730 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
29740 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
29750 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
29760 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
29770 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
29780 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29790 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
297a0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
297b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
297c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
297d0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
297e0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
297f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
29800 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
29810 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
29820 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
29830 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
29840 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
29850 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
29860 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
29870 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
29880 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
29890 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
298a0 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
298b0 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
298c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
298d0 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
298e0 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
298f0 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
29900 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
29910 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29920 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
29930 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
29940 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
29950 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
29960 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
29970 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
29980 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
29990 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
299a0 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
299b0 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
299c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
299d0 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
299e0 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
299f0 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
29a00 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
29a10 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29a20 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29a30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29a40 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
29a50 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
29a60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29a70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
29a80 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
29a90 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
29aa0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
29ab0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
29ac0 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
29ad0 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
29ae0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
29af0 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
29b00 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
29b10 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
29b20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
29b30 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20  ** {H13202}  If 
29b40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29b50 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
29b60 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
29b70 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
29b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29b90 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
29ba0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29bb0 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
29bc0 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
29bd0 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
29be0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
29bf0 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
29c00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29c10 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
29c20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
29c30 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
29c40 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
29c50 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
29c60 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
29c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d  ..**.** {H15304}
29c80 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
29c90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29ca0 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
29cb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29cc0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
29cd0 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
29ce0 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
29cf0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
29d00 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
29d10 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e  * {H15306}  When
29d20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
29d30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
29d40 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
29d50 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
29d60 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
29d70 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
29d80 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
29d90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29da0 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ROW]..**.** {H15
29db0 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
29dc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29dd0 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
29de0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
29df0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
29e00 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
29e10 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
29e20 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
29e30 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
29e40 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
29e50 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
29e60 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
29e70 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
29e80 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
29e90 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
29ea0 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31  E]..**.** {H1531
29eb0 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
29ec0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
29ed0 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
29ee0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
29ef0 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
29f00 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
29f10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29f20 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
29f30 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
29f40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
29f50 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
29f60 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
29f70 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
29f80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29f90 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
29fa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29fb0 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
29fc0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
29fd0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
29fe0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
29ff0 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
2a000 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
2a010 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
2a020 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2a030 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2a040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2a050 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a060 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
2a070 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
2a080 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
2a090 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
2a0a0 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
2a0b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a0c0 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
2a0d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a0e0 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65  * {H13771}  Afte
2a0f0 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
2a100 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
2a110 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
2a120 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20  TE_ROW],.**     
2a130 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2a140 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
2a150 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  ] routine will r
2a160 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
2a170 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
2a180 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65    as the [sqlite
2a190 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
2a1a0 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  )] function..**.
2a1b0 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74  ** {H13772}  Aft
2a1c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2a1d0 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  (S)] has returne
2a1e0 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  d any value othe
2a1f0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
2a200 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d      [SQLITE_ROW]
2a210 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
2a220 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2a230 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2a240 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a250 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a260 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
2a270 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
2a280 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  t was.**        
2a290 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
2a2a0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
2a2b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a2c0 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20  t | reset],.**  
2a2d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2a2e0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a2f0 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  (S)] routine ret
2a300 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
2a310 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2a320 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a330 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a340 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2a350 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2a360 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31  s {H10265} <S101
2a370 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b  10><S10120>.** K
2a380 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2a390 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
2a3a0 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
2a3b0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2a3c0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2a3d0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2a3e0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2a3f0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2a400 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2a410 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2a420 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2a430 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2a440 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2a450 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2a460 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
2a470 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2a480 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2a490 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2a4a0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2a4b0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2a4c0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2a4d0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2a4e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2a4f0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2a500 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2a510 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2a520 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2a530 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2a540 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2a550 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a560 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2a570 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2a580 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2a590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2a5a0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2a5b0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2a5c0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2a5d0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2a5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2a5f0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2a600 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2a610 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2a620 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2a630 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2a640 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2a650 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2a660 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2a670 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2a680 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
2a690 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30  {H13800} <S10700
2a6a0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2a6b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2a6c0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2a6d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2a6e0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2a6f0 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66  et query" interf
2a700 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ace..**.** These
2a710 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a730 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2a740 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2a750 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2a760 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
2a770 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a780 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a790 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a7a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a7b0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a7c0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a7d0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a7e0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a7f0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a810 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a820 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a830 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a840 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a850 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a860 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a870 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a880 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a890 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  d.  The leftmost
2a8a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a8b0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a8c0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a  e index 0..**.**
2a8d0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2a8e0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2a8f0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2a900 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2a910 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2a920 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2a930 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2a940 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a950 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2a960 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2a970 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2a980 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a990 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a9a0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2a9b0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2a9c0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2a9d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2a9e0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2a9f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2aa00 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2aa10 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2aa20 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2aa30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2aa40 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2aa50 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2aa60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2aa70 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2aa80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2aa90 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2aaa0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2aab0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2aac0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2aad0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2aae0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2aaf0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ab00 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2ab10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab20 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2ab30 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2ab40 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2ab50 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2ab60 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2ab70 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2ab80 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2ab90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2aba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2abb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2abc0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2abd0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2abe0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2abf0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2ac00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2ac10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2ac20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2ac30 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2ac40 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2ac50 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2ac60 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2ac70 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2ac80 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2ac90 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2aca0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2acb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2acc0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2acd0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2ace0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2acf0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2ad00 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2ad10 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2ad20 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2ad30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2ad40 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2ad50 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2ad60 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2ad70 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2ad80 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2ad90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ada0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2adb0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2adc0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2add0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
2ade0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2adf0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ae00 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ae10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ae20 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ae30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ae40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ae50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ae60 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
2ae70 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2ae80 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2ae90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2aea0 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2aeb0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2aec0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2aed0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2aee0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
2aef0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2af00 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2af10 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2af20 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2af30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2af40 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2af50 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2af60 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2af70 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2af80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2af90 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2afa0 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
2afb0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
2afc0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2afd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
2afe0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2aff0 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
2b000 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2b010 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
2b020 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2b030 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2b040 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2b050 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2b060 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
2b070 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2b080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b090 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2b0a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2b0b0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2b0c0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2b0d0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
2b0e0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
2b0f0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2b100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b110 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2b120 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
2b130 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
2b140 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
2b150 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
2b160 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2b170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b180 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
2b190 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
2b1a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b1b0 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
2b1c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
2b1d0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2b1e0 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2b1f0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
2b200 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
2b210 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
2b220 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
2b230 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62  nt..**.** The ob
2b240 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2b250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b260 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2b270 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2b280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b290 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2b2a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b2b0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2b2c0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2b2d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2b2e0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2b2f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b300 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2b310 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2b320 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b330 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b340 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2b350 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b360 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2b370 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2b380 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2b390 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2b3a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2b3b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2b3c0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2b3d0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2b3e0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2b3f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b400 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b410 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b420 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2b430 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2b440 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2b450 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
2b460 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2b470 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2b480 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2b490 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2b4a0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2b4b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b4c0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2b4d0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2b4e0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2b4f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2b500 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2b510 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2b520 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2b530 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2b540 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2b550 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2b560 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2b570 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2b580 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2b590 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2b5a0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2b5b0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2b5c0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2b5d0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2b5e0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2b5f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b600 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b610 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2b620 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b630 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2b640 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b650 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b660 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b670 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b680 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b690 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b6a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2b6b0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2b6c0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b6d0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2b6e0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2b6f0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b700 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b710 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2b720 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2b730 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b740 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2b750 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2b760 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2b770 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2b780 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b790 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2b7a0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2b7b0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2b7c0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2b7d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2b7e0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2b7f0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2b800 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b810 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b820 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2b830 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2b840 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b850 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b860 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2b870 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2b880 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b890 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2b8a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b8b0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b8c0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2b8d0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2b8e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2b8f0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b900 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2b910 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2b920 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2b930 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b940 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2b950 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2b960 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b970 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2b980 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2b990 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2b9a0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2b9b0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2b9c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2b9d0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2b9e0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2b9f0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2ba00 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2ba10 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2ba20 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2ba30 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2ba40 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2ba50 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2ba60 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2ba70 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2ba80 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ba90 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2baa0 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2bab0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2bac0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2bad0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2bae0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2baf0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2bb00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2bb10 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2bb20 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2bb30 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2bb40 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2bb50 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2bb60 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2bb70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2bb80 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2bb90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bba0 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2bbb0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2bbc0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2bbd0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2bbe0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2bbf0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2bc00 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2bc10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2bc20 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bc30 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2bc40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bc50 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2bc60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bc70 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2bc80 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2bc90 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2bca0 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2bcb0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2bcc0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2bcd0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2bce0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2bcf0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2bd00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2bd10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2bd20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bd30 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2bd40 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2bd50 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2bd60 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2bd70 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2bd80 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bd90 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2bda0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2bdb0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2bdc0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2bdd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2bde0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2bdf0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2be00 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2be10 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2be20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
2be30 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2be40 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2be50 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2be60 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2be70 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2be80 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2be90 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2bea0 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2beb0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2bec0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2bed0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
2bee0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
2bef0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2bf00 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2bf10 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2bf20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2bf30 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2bf40 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2bf50 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2bf60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2bf70 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2bf80 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2bf90 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2bfa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2bfb0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2bfc0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2bfd0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2bfe0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2bff0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2c000 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2c010 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2c020 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2c030 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2c040 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c050 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2c060 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2c070 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2c080 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2c0a0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2c0b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c0c0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2c0d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c0e0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2c0f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c100 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2c110 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2c120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c130 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2c140 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2c150 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c160 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2c170 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2c180 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2c190 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2c1a0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2c1b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c1c0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c1d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c1e0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2c1f0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2c200 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2c210 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2c220 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2c230 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c240 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2c250 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2c260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c270 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2c280 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2c290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c2a0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2c2b0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2c2c0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2c2d0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
2c2e0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2c2f0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2c300 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2c310 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2c320 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2c330 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2c340 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2c350 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2c360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c370 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
2c380 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2c390 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2c3a0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2c3b0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2c3c0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2c3d0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2c3e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c3f0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2c400 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2c410 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c420 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2c430 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2c440 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
2c450 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c460 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c470 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c480 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c490 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c4a0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c4b0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c4c0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c4d0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c4e0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c4f0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c500 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c510 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c520 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c530 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c540 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c550 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c560 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
2c570 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2c580 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54  **.** {H13803} T
2c590 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2c5a0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
2c5b0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c5c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c5d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2c5e0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2c5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c600 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2c610 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c620 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2c630 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e   a BLOB and then
2c640 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2c650 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2c660 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2c670 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2c680 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
2c690 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c6a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c6b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c6c0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c6d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42  f bytes in the B
2c6e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65  LOB or string (e
2c6f0 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
2c700 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2c710 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
2c720 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
2c730 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
2c740 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c750 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2c760 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2c770 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
2c780 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2c790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c7a0 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
2c7b0 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {H13809} The [sq
2c7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c7d0 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
2c7e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c800 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c810 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
2c820 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c830 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c840 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c850 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c860 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c880 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c890 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c8a0 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
2c8b0 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68  *.** {H13812} Th
2c8c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c8d0 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
2c8e0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c8f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c900 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2c910 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2c920 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c930 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2c940 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2c950 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2c960 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2c970 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2c980 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c990 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c9a0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2c9b0 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
2c9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
2c9d0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c9e0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c9f0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2ca00 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2ca10 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ca20 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2ca30 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2ca40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ca50 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2ca60 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2ca70 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2ca80 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2ca90 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2caa0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2cab0 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {H13818} The [sq
2cac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2cad0 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
2cae0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2caf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2cb00 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2cb10 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2cb20 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2cb30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cb40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cb50 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2cb60 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2cb70 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2cb80 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2cb90 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2cba0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  er..**.** {H1382
2cbb0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2cbc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
2cbd0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2cbe0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2cbf0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2cc00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2cc10 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2cc20 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2cc30 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2cc40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2cc50 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2cc60 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2cc70 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2cc80 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2cc90 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2cca0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2ccb0 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
2ccc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2ccd0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cce0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2ccf0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cd00 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cd10 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cd20 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2cd30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2cd40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cd50 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
2cd60 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2cd70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2cd80 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
2cd90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
2cda0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2cdb0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
2cdc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2cdd0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2cde0 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  13827} The [sqli
2cdf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ce00 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2ce10 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2ce20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2ce30 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2ce40 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2ce50 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2ce60 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2ce70 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2ce80 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2ce90 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2cea0 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63         the Nth c
2ceb0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cec0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2ced0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2cee0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2cef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf00 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
2cf10 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  3830} The [sqlit
2cf20 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2cf30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cf40 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
2cf50 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
2cf60 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2cf70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2cf80 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a  object for the.*
2cf90 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2cfa0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cfb0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2cfc0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2cfd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2cfe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cff0 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  nt] S..*/.const 
2d000 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2d010 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2d020 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d030 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2d040 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2d050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d060 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2d070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d080 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d090 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2d0a0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2d0b0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2d0c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d0d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d0e0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2d0f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d100 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2d110 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2d120 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d130 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d140 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2d150 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d160 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2d170 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d180 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2d190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d1a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2d1b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d1c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d1d0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2d1e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d1f0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2d200 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d210 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d220 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d240 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2d250 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2d260 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53  ject {H13300} <S
2d270 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a  70300><S30100>.*
2d280 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d290 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2d2a0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2d2b0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2d2c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d2d0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
2d2e0 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
2d2f0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
2d300 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
2d310 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
2d320 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
2d330 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
2d340 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2d350 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
2d360 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2d370 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2d380 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2d3a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2d3b0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2d3c0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
2d3d0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
2d3e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d3f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
2d400 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
2d410 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
2d420 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d430 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
2d440 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
2d450 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
2d460 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
2d470 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
2d480 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
2d490 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
2d4a0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
2d4b0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
2d4c0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
2d4d0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
2d4e0 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
2d4f0 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
2d500 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
2d510 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
2d520 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
2d530 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
2d540 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2d550 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68  *.** {H11302} Th
2d560 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
2d570 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
2d580 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
2d590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2d5a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d5b0 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
2d5c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
2d5d0 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
2d5e0 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
2d5f0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
2d600 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20  .** {H11304} If 
2d610 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d630 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2d640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d660 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
2d670 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
2d680 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2d690 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
2d6a0 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
2d6b0 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
2d6c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d6d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d6e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d6f0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2d700 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d710 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30  t Object {H13330
2d720 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
2d730 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d740 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2d750 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2d760 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d770 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d780 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2d790 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2d7a0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2d7b0 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
2d7c0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2d7d0 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2d7e0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2d7f0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2d800 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d810 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2d820 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2d830 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2d840 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2d850 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2d860 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2d870 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
2d880 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  H11332} The [sql
2d890 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2d8a0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2d8b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d8c0 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
2d8d0 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
2d8e0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2d8f0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2d900 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74  ** {H11334} If t
2d910 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2d920 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d930 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2d940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d960 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2d970 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2d980 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
2d990 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
2d9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2d9b0 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2d9c0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2d9d0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
2d9e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2d9f0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2da00 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2da10 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68  * {H11336} If th
2da20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2da30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2da40 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2da50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2da60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2da70 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2da80 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
2da90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2daa0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2dab0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2dac0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2dad0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54  **.** {H11338} T
2dae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2daf0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2db00 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2db10 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
2db20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
2db30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2db40 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2db50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2db60 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2db70 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2db80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2db90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2dba0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2dbb0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2dbc0 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20  ctions {H16100} 
2dbd0 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
2dbe0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2dbf0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2dc00 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2dc10 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2dc20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dc30 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2dc40 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2dc50 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dc60 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2dc70 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
2dc80 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2dc90 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2dca0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2dcb0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2dcc0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2dcd0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2dce0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2dcf0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2dd00 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2dd10 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2dd20 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2dd30 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
2dd40 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
2dd50 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
2dd60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
2dd70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2dd80 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
2dd90 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2dda0 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
2ddb0 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
2ddc0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ddd0 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
2dde0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2ddf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2de00 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
2de10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2de20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2de30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2de40 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2de50 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2de60 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
2de70 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65  ngle program use
2de80 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2de90 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2dea0 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c  ection internall
2deb0 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63  y, then SQL func
2dec0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2ded0 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
2dee0 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61   to.** each data
2def0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2df00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2df10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2df20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2df30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2df40 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2df50 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  redefined.  The 
2df60 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2df70 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2df80 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
2df90 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
2dfa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2dfb0 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
2dfc0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
2dfd0 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
2dfe0 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
2dff0 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
2e000 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2e010 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2e020 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2e030 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2e040 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
2e050 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2e060 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2e070 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2e080 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2e090 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2e0a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2e0b0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2e0c0 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
2e0d0 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
2e0e0 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
2e0f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e100 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2e110 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2e120 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2e130 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2e140 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2e150 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2e160 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2e170 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2e180 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2e190 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2e1a0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2e1b0 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
2e1c0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e1d0 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
2e1e0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
2e1f0 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
2e200 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2e210 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2e220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2e230 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2e240 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2e250 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2e260 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
2e270 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
2e280 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2e290 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2e2a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e2b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2e2c0 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2e2d0 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2e2e0 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2e2f0 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2e300 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2e310 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2e320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e330 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e340 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2e350 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2e360 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2e370 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2e380 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2e390 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2e3a0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2e3b0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2e3c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2e3d0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2e3e0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2e3f0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2e400 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2e410 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2e420 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2e430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
2e440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2e450 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2e460 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2e470 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2e480 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2e490 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2e4a0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2e4b0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2e4c0 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
2e4d0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
2e4e0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
2e4f0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2e500 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2e510 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2e520 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2e530 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2e540 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e550 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e560 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2e570 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2e580 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2e590 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2e5a0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2e5b0 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2e5c0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2e5d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2e5e0 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2e5f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2e600 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2e610 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2e620 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2e630 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2e640 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2e650 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2e660 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2e670 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
2e680 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2e690 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2e6a0 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2e6b0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2e6c0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
2e6d0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
2e6e0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2e6f0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2e700 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e710 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2e720 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2e730 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2e740 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2e750 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2e760 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2e770 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2e780 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2e790 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
2e7a0 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2e7b0 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
2e7c0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2e7d0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2e7e0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2e7f0 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75  n is used.  A fu
2e800 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e810 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2e820 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2e830 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2e840 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2e850 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2e860 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2e870 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2e880 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f  nArg.  A functio
2e890 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2e8a0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e8b0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2e8c0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2e8d0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2e8e0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2e8f0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e900 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2e910 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2e920 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e930 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e940 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2e950 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2e960 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2e970 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2e980 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2e990 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e9a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2e9b0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2e9c0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42  d UTF16..**.** B
2e9d0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2e9e0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2e9f0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2ea00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ea10 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  unctions..** The
2ea20 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
2ea30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ea40 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
2ea50 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
2ea60 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
2ea70 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
2ea80 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2ea90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
2eaa0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
2eab0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70  ** Subsequent ap
2eac0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ead0 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74  d functions of t
2eae0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c  he same name onl
2eaf0 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70  y override .** p
2eb00 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  rior application
2eb10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2eb20 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65  ns that are an e
2eb30 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74  xact match for t
2eb40 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2eb50 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70  parameters and p
2eb60 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e  referred encodin
2eb70 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c  g..**.** An appl
2eb80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2eb90 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
2eba0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
2ebb0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
2ebc0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
2ebd0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
2ebe0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
2ebf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2ec00 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
2ec10 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
2ec20 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
2ec30 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
2ec40 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
2ec50 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2ec60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2ec70 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20  ** {H16103} The 
2ec80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ec90 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e  function16(D,X,.
2eca0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ecb0 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20  hall behave.**  
2ecc0 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69          as [sqli
2ecd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ece0 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
2ecf0 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
2ed00 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
2ed10 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
2ed20 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
2ed30 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2ed40 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2ed50 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2ed60 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2ed70 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2ed80 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2ed90 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2eda0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2edb0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
2edc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2edd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ede0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2edf0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2ee00 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  gister.**       
2ee10 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2ee20 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2ee30 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2ee40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2ee50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2ee60 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2ee70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ee80 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2ee90 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2eea0 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2eeb0 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2eec0 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2eed0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2eee0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2eef0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2ef00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ef10 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2ef20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2ef30 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20 50 2c  l replace the P,
2ef40 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c   F, S, and L val
2ef50 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69  ues from any pri
2ef60 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a  or calls with.**
2ef70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2ef80 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20  me D, X, N, and 
2ef90 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  E values..**.** 
2efa0 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71  {H16112} The [sq
2efb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2efc0 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ction(D,X,...)] 
2efd0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2efe0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
2eff0 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   if the SQL func
2f000 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a  tion name X is.*
2f010 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65  *          longe
2f020 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73  r than 255 bytes
2f030 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2f040 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2f050 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38  r..**.** {H16118
2f060 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2f070 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2f080 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2f090 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
2f0a0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66 61 69         shall fai
2f0b0 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65 72 20  l unless either 
2f0c0 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20  F is NULL and S 
2f0d0 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2f0e0 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20  LL or.***       
2f0f0 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20    F is non-NULL 
2f100 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2f110 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
2f120 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2f130 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f140 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
2f150 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 73 20  ace shall fails 
2f160 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2f170 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2f180 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2f190 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2f1a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f1b0 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2f1c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f1d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f1e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2f1f0 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65  .** {H16124} The
2f200 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f210 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2f220 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2f230 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a  shall fail with.
2f240 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 65  **          an e
2f250 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2f260 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
2f270 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 6c 65  arameter N is le
2f280 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2f290 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2f2a0 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2f2b0 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20  * {H16127} When 
2f2c0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2f2d0 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2f2e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f2f0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2f300 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f310 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72  e shall register
2f320 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2f330 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2f340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2f350 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f360 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2f370 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2f380 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2f390 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2f3a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2f3b0 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2f3c0 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  H16130} When N i
2f3d0 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2f3e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f3f0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2f400 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2f410 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
2f420 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ter callbacks to
2f430 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2f440 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  the SQL.**      
2f450 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d      function nam
2f460 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
2f470 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2f480 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33  s..**.** {H16133
2f490 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f4a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f4b0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2f4c0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2f4d0 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2f4e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f4f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f500 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
2f510 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
2f520 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f530 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
2f540 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
2f550 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
2f560 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f570 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
2f580 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70 72 65  o N shall be pre
2f590 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2f5a0 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2f5b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f5c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f5d0 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2f5e0 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2f5f0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f600 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f610 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2f620 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2f630 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2f640 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2f650 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2f660 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2f670 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2f680 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f690 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2f6a0 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2f6b0 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2f6c0 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72 65 66  oding shall pref
2f6d0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  erred..**.** {H1
2f6e0 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
2f6f0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f700 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
2f710 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2f720 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f730 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2f740 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
2f750 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  alizer.**       
2f760 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68     function L sh
2f770 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  all always be in
2f780 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
2f790 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
2f7a0 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
2f7b0 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
2f7c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2f7d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32  s..**.** {H16142
2f7e0 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
2f7f0 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
2f800 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
2f810 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
2f820 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
2f830 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f840 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2f850 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
2f860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
2f870 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f880 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
2f890 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f8a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
2f8b0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2f8c0 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f8e0 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
2f8f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
2f900 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68  ird parameter sh
2f910 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63 74 65  all be [protecte
2f920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f930 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2f940 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f950 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2f960 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f970 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f980 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f990 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f9a0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f9b0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f9c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f9d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f9e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f9f0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2fa00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fa10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fa20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2fa30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fa40 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2fa50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fa60 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2fa70 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2fa80 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fa90 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2faa0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fab0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fac0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fad0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2faf0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fb00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fb10 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fb20 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fb30 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fb40 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2fb50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2fb60 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
2fb70 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
2fb80 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
2fb90 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2fba0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2fbb0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2fbc0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2fbd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2fbe0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2fbf0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2fc00 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2fc10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2fc20 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2fc30 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2fc40 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2fc50 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2fc60 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2fc70 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2fc80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2fc90 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2fca0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2fcb0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2fcc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fcd0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2fce0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fcf0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2fd00 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2fd10 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2fd20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2fd30 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2fd40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2fd50 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2fd60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2fd70 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2fd80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2fd90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2fda0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2fdb0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2fdc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2fdd0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2fde0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2fdf0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2fe00 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2fe10 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2fe20 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2fe30 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2fe40 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2fe50 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2fe60 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2fe70 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2fe80 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2fe90 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2fea0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2feb0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2fec0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fed0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2fee0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2fef0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2ff00 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2ff10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2ff20 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2ff30 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2ff40 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ff50 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2ff60 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2ff70 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2ff80 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2ff90 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2ffa0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2ffb0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2ffc0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2ffd0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2ffe0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2fff0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30000 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
30010 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
30020 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
30030 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
30040 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
30050 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
30060 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
30070 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
30080 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
30090 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
300a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
300b0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
300c0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
300d0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
300e0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
300f0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
30100 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
30110 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
30120 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
30130 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
30140 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
30150 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
30160 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
30170 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
30180 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
30190 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
301a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
301b0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
301c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
301d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
301e0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
301f0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
30200 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30210 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30220 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
30230 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
30240 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
30250 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
30260 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
30270 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30280 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
30290 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
302a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
302b0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
302c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
302d0 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
302e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
302f0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
30300 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
30310 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30320 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
30330 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
30340 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
30350 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30360 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30370 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
30380 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
30390 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
303a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
303b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
303c0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
303d0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
303e0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
303f0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
30400 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
30410 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
30420 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
30430 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
30440 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
30450 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
30460 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30470 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30480 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
30490 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
304a0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
304b0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
304c0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
304d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
304e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
304f0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
30500 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
30510 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
30520 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
30530 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
30540 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
30550 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30560 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
30570 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
30580 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30590 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
305a0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
305b0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
305c0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
305d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
305f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
30630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
30640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
30650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
30660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
30670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
30680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
30690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
306a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
306b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
306c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
306d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
306e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
306f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
30700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
30710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
30720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
30730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
30740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
30750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
30760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
30770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
30780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
30790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
307a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
307b0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
307c0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
307d0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
307e0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
307f0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
30800 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
30810 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30820 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
30830 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30840 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
30850 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
30860 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30870 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
30880 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
30890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
308a0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
308b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
308c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
308d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
308e0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
308f0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30900 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30910 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
30920 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
30930 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
30940 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
30950 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
30960 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
30970 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
30980 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
30990 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
309a0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
309b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
309c0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
309d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
309e0 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
309f0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
30a00 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30a10 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
30a20 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
30a30 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
30a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30a50 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
30a60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
30a70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
30a80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30a90 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
30aa0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
30ab0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
30ac0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
30ad0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
30ae0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
30af0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
30b00 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
30b10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30b20 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
30b30 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
30b40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30b50 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
30b60 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
30b70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30b80 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
30b90 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
30ba0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
30bb0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
30bc0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
30bd0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
30be0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
30bf0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
30c00 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
30c10 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
30c20 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
30c30 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30c50 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
30c60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
30c70 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
30c80 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
30c90 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
30ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
30cb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30cc0 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
30cd0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30ce0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30cf0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30d00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30d10 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
30d20 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
30d30 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30d40 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30d50 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
30d60 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
30d70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30d80 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
30d90 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
30da0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
30db0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30dc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
30dd0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
30de0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
30df0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30e00 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
30e10 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
30e20 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
30e30 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
30e40 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
30e50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30e60 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
30e70 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
30e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30e90 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
30ea0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
30eb0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
30ec0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30ed0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
30ee0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
30ef0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
30f00 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
30f10 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30f20 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30f30 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30f40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30f50 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
30f60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
30f70 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
30f80 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
30f90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30fa0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
30fb0 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
30fc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30fd0 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
30fe0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
31000 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31010 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
31020 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
31030 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
31040 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
31050 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
31060 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
31070 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
31080 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
31090 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
310a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
310b0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
310c0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
310d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
310e0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
310f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
31100 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31110 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
31120 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
31130 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
31140 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
31150 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
31160 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
31170 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31180 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31190 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
311a0 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
311b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
311c0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
311d0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
311e0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
311f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31200 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
31210 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31220 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
31230 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
31240 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
31250 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
31260 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
31270 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31280 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
31290 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
312a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
312b0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
312c0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
312d0 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
312e0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
312f0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
31300 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
31310 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31320 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
31330 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
31340 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
31350 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
31360 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31370 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
31380 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
31390 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
313a0 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
313b0 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
313c0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
313d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
313e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
313f0 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
31400 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
31410 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
31420 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
31430 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
31440 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
31450 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
31460 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
31470 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
31480 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
31490 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
314a0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
314b0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
314c0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
314d0 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
314e0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
314f0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
31500 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31510 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31520 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
31530 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
31540 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
31550 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
31560 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
31570 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31580 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31590 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
315a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
315b0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
315c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
315d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
315e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
315f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31600 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
31610 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
31620 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
31630 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
31640 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31650 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
31660 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
31670 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
31680 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31690 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
316a0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
316b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
316c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
316d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
316e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
316f0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31700 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31710 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
31720 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31730 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
31740 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31750 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
31760 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
31770 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
31780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
31790 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
317a0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
317b0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
317c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
317d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
317e0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
317f0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
31800 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31810 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
31820 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
31830 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
31840 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
31850 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
31860 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
31870 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
31880 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
31890 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
318a0 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
318b0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
318c0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
318d0 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
318e0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
318f0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
31900 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31910 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
31920 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
31930 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
31940 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
31950 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
31960 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
31970 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
31980 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
31990 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
319a0 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
319b0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
319c0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
319d0 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
319e0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
319f0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
31a00 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
31a10 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
31a20 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
31a30 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
31a40 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31a50 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
31a60 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31a70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31a80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31a90 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31aa0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31ab0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
31ac0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
31ad0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31ae0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31af0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
31b00 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
31b10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31b20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31b30 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
31b40 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31b50 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
31b60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
31b70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
31b80 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
31b90 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
31ba0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31bb0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
31bc0 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
31bd0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
31be0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
31bf0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
31c00 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
31c10 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
31c20 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
31c30 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
31c40 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
31c50 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
31c60 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31c70 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
31c80 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
31c90 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
31ca0 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
31cb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31cc0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
31cd0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
31ce0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
31cf0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
31d00 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
31d10 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
31d20 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
31d30 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31d40 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
31d50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
31d60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31d70 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
31d80 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
31d90 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
31da0 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
31db0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
31dc0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31dd0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
31de0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
31df0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
31e00 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
31e10 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
31e20 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
31e30 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
31e40 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
31e50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31e60 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
31e70 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
31e80 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
31e90 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
31ea0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31ec0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31ed0 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
31ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31ef0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
31f00 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
31f10 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
31f20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
31f30 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
31f40 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
31f50 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
31f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31f70 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
31f80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
31f90 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
31fa0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
31fb0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
31fc0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
31fd0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31fe0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
31ff0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32000 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
32010 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
32020 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
32030 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
32040 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32050 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32060 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32070 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32080 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32090 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
320a0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
320b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
320c0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
320d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
320e0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
320f0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32100 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
32110 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32120 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32130 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
32140 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
32150 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
32160 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
32170 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
32180 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32190 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
321a0 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
321b0 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
321c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
321d0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
321e0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
321f0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
32200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32210 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
32220 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
32230 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
32240 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
32250 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
32260 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
32270 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
32280 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
32290 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
322a0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
322b0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
322c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
322d0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
322e0 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
322f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
32300 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32310 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
32320 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
32330 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
32340 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
32350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32360 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
32370 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
32380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32390 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
323a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
323b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
323c0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
323d0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
323e0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
323f0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32400 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32410 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
32420 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
32430 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
32440 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
32450 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32460 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
32470 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
32480 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
32490 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
324a0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
324b0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
324c0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
324d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
324e0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
324f0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
32500 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
32510 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
32520 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
32530 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
32540 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
32550 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
32560 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
32570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32590 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
325a0 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
325b0 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
325c0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
325d0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
325e0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
325f0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32600 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
32610 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
32620 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
32630 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
32640 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
32650 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
32660 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
32670 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
32680 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
32690 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
326a0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
326b0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
326c0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
326d0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
326e0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
326f0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
32700 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
32710 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
32720 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
32730 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
32740 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
32750 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
32760 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
32770 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
32780 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32790 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
327a0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
327b0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
327c0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
327d0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
327e0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
327f0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
32800 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
32810 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32820 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
32830 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
32840 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
32850 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
32860 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
32870 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
32880 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
32890 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
328a0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
328b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
328c0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
328d0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
328e0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
328f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32900 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
32910 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
32920 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
32930 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32940 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
32950 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
32960 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
32970 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
32980 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
32990 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
329a0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
329b0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
329c0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
329d0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
329e0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
329f0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
32a00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32a10 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
32a20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
32a30 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32a40 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32a50 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
32a60 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
32a70 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
32a80 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
32a90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
32aa0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
32ab0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
32ac0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32ad0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
32ae0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
32af0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32b00 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
32b10 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
32b20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
32b30 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
32b40 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
32b50 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
32b60 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32b70 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
32b80 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
32b90 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32ba0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32bb0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
32bc0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
32bd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32be0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32bf0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
32c00 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
32c10 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
32c20 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
32c30 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
32c40 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
32c50 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
32c60 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
32c70 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
32c80 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
32c90 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
32ca0 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
32cb0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
32cc0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
32cd0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
32ce0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
32cf0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
32d00 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
32d10 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32d20 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32d30 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32d40 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32d50 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
32d60 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
32d70 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
32d80 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
32d90 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32da0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
32db0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32dc0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
32dd0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
32de0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
32df0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
32e00 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32e10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32e20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
32e30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
32e40 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
32e50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32e60 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32e70 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
32e80 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32e90 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
32ea0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
32eb0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
32ec0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
32ed0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
32ee0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
32ef0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
32f00 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
32f10 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
32f20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
32f30 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
32f40 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32f50 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
32f60 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
32f70 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
32f80 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
32f90 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
32fa0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
32fb0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
32fc0 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
32fd0 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
32fe0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32ff0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
33000 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
33010 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
33020 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
33030 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
33040 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
33050 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33060 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33070 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
33080 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
33090 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
330a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
330b0 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
330c0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
330d0 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
330e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
330f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
33100 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
33110 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
33120 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
33130 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
33140 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
33150 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
33160 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
33170 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
33180 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
33190 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
331a0 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
331b0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
331c0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
331d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
331e0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
331f0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
33200 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
33210 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
33220 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
33230 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
33240 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
33250 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
33260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33270 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
33280 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33290 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
332a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
332b0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
332c0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
332d0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
332e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
332f0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
33300 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33310 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33320 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
33330 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
33340 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
33350 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
33360 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
33370 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
33380 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
33390 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
333a0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
333b0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
333c0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
333d0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
333e0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
333f0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
33400 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
33410 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
33420 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
33430 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
33440 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
33450 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
33460 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
33470 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
33480 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
33490 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
334a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
334b0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
334c0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
334d0 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
334e0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
334f0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33500 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33510 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33520 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
33530 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
33540 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
33550 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
33560 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
33570 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
33580 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33590 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
335a0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
335b0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
335c0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
335d0 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
335e0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
335f0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
33600 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
33610 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
33620 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
33630 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
33640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
33650 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
33660 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
33670 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
33680 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
33690 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
336a0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
336b0 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
336c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
336d0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
336e0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
336f0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33700 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33710 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33720 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
33730 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
33740 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33750 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
33760 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33770 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
33780 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33790 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
337a0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
337b0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
337c0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
337d0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
337e0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
337f0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33800 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
33810 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
33820 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
33830 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
33840 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
33850 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
33860 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33870 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
33880 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33890 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
338a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
338b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
338c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
338d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
338e0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
338f0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
33900 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
33910 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
33920 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
33930 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
33940 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
33950 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
33960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33970 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
33980 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
33990 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
339a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
339b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
339c0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
339d0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
339e0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
339f0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
33a00 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
33a10 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
33a20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
33a30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33a40 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
33a50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33a60 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
33a70 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
33a80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33a90 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
33aa0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
33ab0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
33ac0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33ad0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33ae0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33af0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33b00 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
33b10 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
33b20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33b40 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33b50 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
33b60 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
33b70 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
33b80 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
33b90 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
33ba0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
33bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33bc0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33bd0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33be0 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
33bf0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
33c00 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33c10 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
33c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33c30 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
33c40 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
33c50 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
33c60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33c70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
33c80 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
33c90 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
33ca0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
33cb0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33cc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33cd0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
33ce0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33cf0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
33d00 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33d10 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
33d20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
33d30 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
33d40 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
33d50 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
33d60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33d70 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33d80 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
33d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33da0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
33db0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33dc0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
33dd0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
33de0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
33df0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33e00 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
33e10 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
33e20 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33e30 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33e40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33e50 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
33e60 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
33e70 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
33e80 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33e90 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
33ea0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
33eb0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
33ec0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
33ed0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
33ee0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
33ef0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
33f00 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
33f10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f20 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
33f30 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
33f40 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
33f50 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
33f60 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
33f70 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
33f80 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
33f90 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
33fa0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
33fb0 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
33fc0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
33fd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33fe0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
33ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34000 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
34010 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
34020 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
34030 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
34040 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
34050 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34060 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34070 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
34080 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
34090 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
340a0 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
340b0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
340c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
340d0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
340e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
340f0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
34100 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
34110 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
34120 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
34130 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
34140 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
34150 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
34160 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
34170 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
34180 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34190 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
341a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
341b0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
341c0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
341d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
341e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
341f0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
34200 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34210 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34220 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34230 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34240 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
34250 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
34260 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
34270 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
34280 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
34290 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
342a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
342b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
342c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
342d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
342e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
342f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
34300 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34310 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34320 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
34330 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
34340 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
34350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34360 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
34370 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
34380 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34390 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
343a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
343b0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
343c0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
343d0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
343e0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
343f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34400 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34410 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34420 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
34430 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
34440 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
34450 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
34460 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
34470 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
34480 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
34490 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
344a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
344b0 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
344c0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
344d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
344e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
344f0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
34500 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
34510 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
34520 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
34530 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
34540 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
34550 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
34560 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
34570 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
34580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34590 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
345a0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
345b0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
345c0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
345d0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
345e0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
345f0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
34600 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
34610 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
34620 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
34630 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
34640 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
34650 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34670 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34680 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34690 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
346a0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
346b0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
346c0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
346d0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
346e0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
346f0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
34700 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
34710 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
34720 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
34730 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34740 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34750 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34760 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
34770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34780 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
34790 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
347a0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
347b0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
347c0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
347d0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
347e0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
347f0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
34800 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
34810 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
34820 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
34830 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
34840 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
34850 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
34860 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34870 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34880 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
34890 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
348a0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
348b0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
348c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
348d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
348e0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
348f0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
34900 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
34910 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
34920 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
34930 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
34940 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34950 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
34960 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34970 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
34980 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34990 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
349a0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
349b0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
349c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
349d0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
349e0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
349f0 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
34a00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34a10 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34a20 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34a30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
34a40 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
34a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34a60 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
34a70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
34a80 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
34a90 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
34aa0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
34ab0 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
34ac0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
34ad0 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
34ae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34af0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
34b00 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
34b10 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
34b20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34b30 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
34b40 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
34b50 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
34b60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34b70 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
34b80 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
34b90 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
34ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34bb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
34bc0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
34bd0 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
34be0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
34bf0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
34c00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34c10 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
34c20 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
34c30 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
34c40 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
34c50 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34c60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34c70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
34c80 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
34c90 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
34ca0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
34cb0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
34cc0 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34ce0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
34cf0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34d00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34d10 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34d20 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
34d30 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
34d40 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
34d50 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
34d60 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
34d70 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
34d80 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
34d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
34da0 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
34db0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34dc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34dd0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34de0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
34df0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
34e00 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
34e10 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
34e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34e30 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
34e40 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34e50 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
34e60 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
34e70 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
34e80 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
34e90 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
34ea0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
34eb0 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
34ec0 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
34ed0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
34ee0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
34ef0 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
34f00 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
34f10 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
34f20 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
34f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
34f40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34f50 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
34f60 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
34f70 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
34f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
34f90 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
34fa0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
34fb0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
34fc0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
34fd0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
34fe0 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
34ff0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
35000 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
35010 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
35020 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
35030 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
35040 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
35050 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
35060 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
35070 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
35080 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
35090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
350a0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
350b0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
350c0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
350d0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
350e0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
350f0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35100 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35110 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
35120 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
35130 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
35140 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
35150 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
35160 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
35170 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
35180 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
35190 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
351a0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
351b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
351c0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
351d0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
351e0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
351f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
35200 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
35210 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
35220 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
35230 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
35240 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35250 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
35260 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
35270 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
35280 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
35290 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
352a0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
352b0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
352c0 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
352d0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
352e0 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
352f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
35300 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
35310 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
35320 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
35330 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
35340 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
35350 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
35360 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
35370 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
35380 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
35390 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
353a0 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
353b0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
353c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
353d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
353e0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
353f0 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
35400 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
35410 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
35420 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35430 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
35440 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35450 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35460 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35470 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
35480 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
35490 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
354a0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
354b0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
354c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
354d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
354e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
354f0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35500 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
35510 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
35520 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
35530 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
35540 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
35550 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
35560 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
35570 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
35580 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
35590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
355a0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
355b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
355c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
355d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
355e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
355f0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
35600 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
35610 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
35620 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
35630 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
35640 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
35650 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
35660 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
35670 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
35680 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
35690 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
356a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
356b0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
356c0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
356d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
356e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
356f0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35700 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
35710 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
35720 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
35730 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
35740 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
35750 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
35760 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
35770 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
35780 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
35790 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
357a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
357b0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
357c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
357d0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
357e0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
357f0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35800 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
35810 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
35820 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
35830 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
35840 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
35850 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
35860 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
35870 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
35880 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
35890 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
358a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
358b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
358c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
358d0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
358e0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
358f0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35900 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
35910 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35920 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
35930 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
35940 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
35950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
35960 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
35970 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35980 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35990 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
359a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
359b0 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
359c0 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
359d0 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
359e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
359f0 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
35a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35a10 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
35a20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
35a30 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
35a40 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
35a50 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
35a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
35a70 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
35a80 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
35a90 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
35aa0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
35ab0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
35ac0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35ad0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35ae0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
35af0 29 5d 2c 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 28 43 2c 56 2c 4e  ult_text16(C,V,N
35b10 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35b20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35b30 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35b40 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
35b50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35b60 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
35b70 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
35b80 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
35b90 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
35ba0 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
35bb0 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
35bc0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
35bd0 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
35be0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
35bf0 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
35c00 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
35c10 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
35c20 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
35c30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
35c40 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35c50 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35c60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35c70 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
35c80 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
35c90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
35ca0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
35cb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35cc0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
35cd0 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
35ce0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35cf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35d00 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
35d10 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
35d20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
35d30 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
35d40 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
35d50 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35d60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
35d70 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
35d80 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
35d90 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
35da0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
35db0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
35dc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35dd0 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
35de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35e00 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [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 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
35e30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35e40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35e50 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
35e60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
35e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35e80 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
35e90 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
35ea0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
35eb0 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
35ec0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
35ed0 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
35ee0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
35ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
35f00 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
35f10 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
35f20 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
35f30 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
35f40 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
35f50 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
35f60 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
35f70 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
35f80 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
35f90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35fa0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
35fb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35fc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35fd0 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
35fe0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
35ff0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
36000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36020 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36030 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
36040 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36060 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
36070 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36080 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36090 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
360a0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
360b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
360c0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
360d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
360e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
360f0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
36100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36110 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36120 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
36130 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36140 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36150 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
36160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36170 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
36180 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36190 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
361a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
361b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
361c0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
361d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
361e0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
361f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36200 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36210 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
36220 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36230 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36240 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36260 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
36270 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36280 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
36290 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
362a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
362b0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
362c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
362d0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
362e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
362f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36300 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
36310 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36320 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
36330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
36340 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
36350 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
36360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36370 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
36380 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
36390 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
363a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
363b0 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
363c0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
363d0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
363e0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
363f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36400 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36410 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
36430 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
36440 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
36450 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
36460 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
36470 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
36480 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
36490 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
364a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
364b0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
364c0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
364d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
364e0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
364f0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
36500 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
36510 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
36520 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
36530 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
36540 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
36550 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
36560 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
36570 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
36580 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
36590 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
365a0 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
365b0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
365c0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
365d0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
365e0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
365f0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
36600 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
36610 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
36620 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
36630 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
36640 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
36650 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
36660 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
36670 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
36680 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
36690 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
366a0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
366b0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
366c0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
366d0 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
366e0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
366f0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
36700 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
36710 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
36720 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
36730 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
36740 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
36750 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
36760 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
36770 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
36780 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
36790 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
367a0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
367b0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
367c0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
367d0 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
367e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
367f0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
36800 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
36810 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
36820 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
36830 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
36840 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
36850 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
36860 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
36870 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36880 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
36890 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
368a0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
368b0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
368c0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
368d0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
368e0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
368f0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
36900 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
36910 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
36920 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
36930 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
36940 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
36950 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
36960 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
36970 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
36980 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
36990 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
369a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
369b0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
369c0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
369d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
369e0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
369f0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
36a00 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
36a10 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
36a20 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
36a30 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
36a40 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
36a50 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
36a60 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
36a70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36a80 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
36a90 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
36aa0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36ab0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
36ac0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
36ad0 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
36ae0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
36af0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
36b00 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
36b10 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
36b20 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
36b30 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
36b40 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
36b50 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
36b60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
36b70 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
36b80 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
36b90 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36ba0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
36bb0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
36bc0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
36bd0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
36be0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
36bf0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
36c00 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36c10 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
36c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36c30 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
36c40 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36c50 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36c60 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36c70 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
36c80 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
36c90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36ca0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36cb0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36cc0 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
36cd0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
36ce0 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
36cf0 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
36d00 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
36d10 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
36d20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
36d30 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
36d40 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36d50 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
36d60 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
36d70 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
36d80 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
36d90 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
36da0 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
36db0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
36dc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36dd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36de0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
36df0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
36e00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
36e10 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
36e20 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
36e30 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
36e40 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
36e50 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
36e60 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
36e70 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
36e80 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
36e90 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
36ea0 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
36eb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36ec0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36ed0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
36ee0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
36ef0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
36f00 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
36f10 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
36f20 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
36f30 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
36f40 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
36f50 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
36f60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36f80 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
36f90 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
36fa0 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
36fb0 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
36fc0 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
36fd0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
36fe0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
36ff0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
37000 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
37010 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
37020 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
37030 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
37040 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
37050 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
37060 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37070 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
37080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37090 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
370a0 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
370b0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
370c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
370d0 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
370e0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
370f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37100 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
37110 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
37120 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
37130 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
37140 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
37150 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
37160 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
37170 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
37180 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
37190 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
371a0 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
371b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
371c0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
371d0 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
371e0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
371f0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
37200 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37210 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
37220 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
37230 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
37240 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
37250 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
37260 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
37270 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
37280 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37290 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
372a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
372b0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
372c0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
372d0 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
372e0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
372f0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
37300 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
37310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37320 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
37330 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
37340 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
37350 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
37360 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
37370 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
37380 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37390 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
373a0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
373b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
373c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
373d0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
373e0 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
373f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37400 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
37410 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
37420 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
37430 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
37440 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
37450 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
37460 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
37470 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
37480 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
37490 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
374a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
374b0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
374c0 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
374d0 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
374e0 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
374f0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
37500 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
37510 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
37520 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
37530 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
37540 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
37550 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
37560 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
37570 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37580 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
37590 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
375a0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
375b0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
375c0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
375d0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
375e0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
375f0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
37600 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37610 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
37620 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
37630 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
37640 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
37650 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
37660 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
37670 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37680 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37690 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
376a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
376b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
376c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
376d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
376e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
376f0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
37700 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
37710 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
37720 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37730 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
37740 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
37750 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
37760 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
37770 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
37780 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
37790 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
377a0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
377b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
377c0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
377d0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
377e0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
377f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
37800 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
37810 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
37820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37830 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
37840 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
37850 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
37860 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
37870 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
37880 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
37890 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
378a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
378b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
378c0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
378d0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
378e0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
378f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37900 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
37910 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
37920 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
37930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37940 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
37950 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
37960 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
37970 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
37980 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
37990 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
379a0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
379b0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
379c0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
379d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
379e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
379f0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
37a00 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
37a10 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
37a20 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
37a30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
37a40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37a50 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
37a60 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37a70 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
37a80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
37a90 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37aa0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
37ab0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
37ac0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
37ad0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
37ae0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
37af0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37b00 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
37b10 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
37b20 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
37b30 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37b40 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
37b50 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
37b60 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
37b70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
37b80 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
37b90 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
37ba0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37bb0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
37bc0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
37bd0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
37be0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
37bf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37c00 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
37c10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37c20 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
37c30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37c40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37c50 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
37c60 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
37c70 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
37c80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
37c90 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
37ca0 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
37cb0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
37cc0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37cd0 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
37ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37d00 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
37d10 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
37d20 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
37d30 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
37d40 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
37d50 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
37d60 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
37d70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37d80 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
37d90 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
37da0 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
37db0 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
37dc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37dd0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
37de0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
37df0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
37e00 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37e10 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
37e20 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
37e30 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
37e40 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
37e50 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
37e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
37e70 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
37e80 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
37e90 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
37ea0 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
37eb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
37ec0 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
37ed0 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
37ee0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
37ef0 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
37f00 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37f10 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
37f20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37f30 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
37f40 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
37f50 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37f60 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
37f70 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
37f80 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37f90 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
37fa0 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
37fb0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
37fc0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
37fd0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37fe0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
37ff0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
38000 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
38010 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
38020 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
38030 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
38040 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
38050 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
38060 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
38070 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
38080 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
38090 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
380a0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
380b0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
380c0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
380d0 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
380e0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
380f0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
38100 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
38110 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
38120 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
38130 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
38140 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
38150 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
38160 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
38170 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
38180 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
38190 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
381a0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
381b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
381c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
381d0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
381e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
381f0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38200 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
38220 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
38230 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
38240 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
38250 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
38260 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
38270 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
38280 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
38290 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
382a0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
382b0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
382c0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
382d0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
382e0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
382f0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
38300 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38310 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38320 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
38330 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38350 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38360 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38370 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
38380 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
38390 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
383a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
383b0 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
383c0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
383d0 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
383e0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
383f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
38400 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
38410 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
38420 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
38430 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
38440 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
38450 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
38460 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
38470 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
38480 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
38490 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
384a0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
384b0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
384c0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
384d0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
384e0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
384f0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
38500 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
38510 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
38520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
38530 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
38540 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
38550 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
38560 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
38570 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
38580 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
38590 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
385a0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
385b0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
385c0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
385d0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
385e0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
385f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38600 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
38610 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38620 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
38630 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
38640 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
38650 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
38660 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
38670 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
38680 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
38690 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
386a0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
386b0 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
386c0 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
386d0 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
386e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
386f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38700 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
38710 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
38720 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
38730 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
38740 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
38750 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
38760 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
38770 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
38780 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
38790 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
387a0 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
387b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
387c0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
387d0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
387e0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
387f0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
38800 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
38810 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
38820 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
38830 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
38840 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
38850 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
38860 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
38870 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
38880 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
38890 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
388a0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
388b0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
388c0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
388d0 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
388e0 72 69 61 62 6