/ Hex Artifact Content
Login

Artifact 4bdbaff3e6ec9eb8e9bdf18933013c07f33cf1ab:


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 33 37 33 20 32 30 30 38 2f 30  n,v 1.373 2008/0
05f0: 37 2f 32 32 20 31 38 3a 34 35 3a 30 39 20 64 72  7/22 18:45:09 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 3c  umbers {H10010}<
0840: 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60100>.**.** Th
0850: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0860: 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52 53   and SQLITE_VERS
0870: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0880: 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71  nes in.** the sq
0890: 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70 65  lite3.h file spe
08a0: 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f 6e  cify the version
08b0: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68 20   of SQLite with 
08c0: 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68 65  which.** that he
08d0: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
08e0: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  ociated..**.** T
08f0: 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66 20  he "version" of 
0900: 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72 69  SQLite is a stri
0910: 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ng of the form "
0920: 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70  X.Y.Z"..** The p
0930: 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f 72  hrase "alpha" or
0940: 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62 65   "beta" might be
0950: 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72 20   appended after 
0960: 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20  the Z..** The X 
0970: 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20 76  value is major v
0980: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c  ersion number al
0990: 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74 65  ways 3 in SQLite
09a0: 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  3..** The X valu
09b0: 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  e only changes w
09c0: 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63 6f  hen backwards co
09d0: 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a 2a  mpatibility is.*
09e0: 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20  * broken and we 
09f0: 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72 20  intend to never 
0a00: 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73 20  break backwards 
0a10: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
0a20: 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69 73  * The Y value is
0a30: 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69   the minor versi
0a40: 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e  on number and on
0a50: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 0a  ly changes when.
0a60: 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61 6a  ** there are maj
0a70: 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61 6e  or feature enhan
0a80: 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  cements that are
0a90: 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61 74   forwards compat
0aa0: 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ible.** but not 
0ab0: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0ac0: 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76  ible..** The Z v
0ad0: 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c 65  alue is the rele
0ae0: 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20 69  ase number and i
0af0: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77 69  s incremented wi
0b00: 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65 61  th.** each relea
0b10: 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62 61  se but resets ba
0b20: 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65 72  ck to 0 whenever
0b30: 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65   Y is incremente
0b40: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
0b50: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
0b60: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
0b70: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
0b80: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a  n_number()]..**.
0b90: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
0ba0: 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54 68  *.** {H10011} Th
0bb0: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0bc0: 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65 20   #define in the 
0bd0: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0be0: 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20 20   file shall.**  
0bf0: 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74 65          evaluate
0c00: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0c10: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0c20: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 0a   SQLite version.
0c30: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
0c40: 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64 65   which the heade
0c50: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
0c60: 61 74 65 64 2e 20 3c 53 36 30 31 30 30 3e 0a 2a  ated. <S60100>.*
0c70: 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d 20 54 68  *.** {H10014} Th
0c80: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0c90: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20  _NUMBER #define 
0ca0: 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f  shall resolve to
0cb0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
0cc0: 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
0cd0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0ce0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0cf0: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d00: 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  Z.**          ar
0d10: 65 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73  e the major vers
0d20: 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69  ion, minor versi
0d30: 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61 73 65 20  on, and release 
0d40: 6e 75 6d 62 65 72 2e 0a 2a 2a 20 20 20 20 20 20  number..**      
0d50: 20 20 20 20 3c 53 36 30 31 30 30 3e 0a 2a 2f 0a      <S60100>.*/.
0d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0d70: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22  ERSION         "
0d80: 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e  --VERS--".#defin
0d90: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
0da0: 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45 52 53 49  _NUMBER  --VERSI
0db0: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a  ON-NUMBER--../*.
0dc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
0dd0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
0de0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
0df0: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
0e00: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
0e10: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
0e20: 2a 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65  ** These feature
0e30: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
0e40: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
0e50: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
0e60: 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53  RSION].** and [S
0e70: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0e80: 4d 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69  MBER] #defines i
0e90: 6e 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75  n the header, bu
0ea0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
0eb0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62  .** with the lib
0ec0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
0ed0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
0ee0: 20 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72    Cautious progr
0ef0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20  ammers might.** 
0f00: 69 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20  include a check 
0f10: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
0f20: 74 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74  tion to verify t
0f30: 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  hat.** sqlite3_l
0f40: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
0f50: 28 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  () always return
0f60: 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b  s the value.** [
0f70: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0f80: 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  UMBER]..**.** Th
0f90: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
0fa0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20  sion() function 
0fb0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65  returns the same
0fc0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
0fd0: 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c  is.** in the sql
0fe0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
0ff0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
1000: 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   The function is
1010: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
1020: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1030: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1040: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1050: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
1060: 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73  o string.** cons
1070: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1080: 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   DLL..**.** INVA
1090: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
10a0: 31 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  10021} The [sqli
10b0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
10c0: 75 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61  umber()] interfa
10d0: 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a  ce shall return.
10e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 69  **          an i
10f0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 20  nteger equal to 
1100: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
1110: 4e 55 4d 42 45 52 5d 2e 20 3c 53 36 30 31 30 30  NUMBER]. <S60100
1120: 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d  >.**.** {H10022}
1130: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65   The [sqlite3_ve
1140: 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f  rsion] string co
1150: 6e 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e  nstant shall con
1160: 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tain.**         
1170: 20 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65   the text of the
1180: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1190: 5d 20 73 74 72 69 6e 67 2e 20 3c 53 36 30 31 30  ] string. <S6010
11a0: 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 33  0>.**.** {H10023
11b0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
11c0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e  ibversion()] fun
11d0: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75  ction shall retu
11e0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
11f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1200: 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e  [sqlite3_version
1210: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1220: 74 2e 20 3c 53 36 30 31 30 30 3e 0a 2a 2f 0a 53  t. <S60100>.*/.S
1230: 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e  QLITE_EXTERN con
1240: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
1250: 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74  version[];.const
1260: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
1270: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
1280: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62  .int sqlite3_lib
1290: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
12a0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
12b0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
12c0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
12d0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 20  y Is Threadsafe 
12e0: 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31 30 30  {H10100} <S60100
12f0: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
1300: 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77  an be compiled w
1310: 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d  ith or without m
1320: 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a  utexes.  When.**
1330: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1340: 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72  EADSAFE] C prepr
1350: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73  ocessor macro is
1360: 20 74 72 75 65 2c 20 6d 75 74 65 78 65 73 0a 2a   true, mutexes.*
1370: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1380: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1390: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
13a0: 61 74 20 6d 61 63 72 6f 20 69 73 20 66 61 6c 73  at macro is fals
13b0: 65 2c 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  e,.** the mutexe
13c0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
13d0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
13e0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
13f0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1400: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1410: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1420: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1430: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1440: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1450: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1460: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1470: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1480: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1490: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
14a0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
14b0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
14c0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
14d0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
14e0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
14f0: 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  d..** The defaul
1500: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1510: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1520: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1530: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1540: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70  n be used by a p
1550: 72 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73  rogram to make s
1560: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
1570: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
1580: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
1590: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
15a0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15b0: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
15c0: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
15d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
15f0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
1600: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
1610: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
1620: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
1630: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1640: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
1650: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1660: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
1670: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1680: 3d 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =1 then mutexes 
1690: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
16a0: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
16b0: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
16c0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
16d0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
16e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
16f0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
1700: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
1710: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1720: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
1730: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
1740: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
1750: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54  ONFIG_MUTEX].  T
1760: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1770: 6f 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  of this function
1780: 20 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74   shows.** only t
1790: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69  he default compi
17a0: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c  le-time setting,
17b0: 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d   not any run-tim
17c0: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
17d0: 74 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  that setting..**
17e0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
17f0: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54  **.** {H10101} T
1800: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  he [sqlite3_thre
1810: 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69  adsafe()] functi
1820: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
1830: 6e 6f 6e 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20  nonzero if.**   
1840: 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 61         SQLite wa
1850: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1860: 74 68 65 20 69 74 73 20 6d 75 74 65 78 65 73 20  the its mutexes 
1870: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1880: 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  lt.**          o
1890: 72 20 7a 65 72 6f 20 69 66 20 53 51 4c 69 74 65  r zero if SQLite
18a0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 73 75   was compiled su
18b0: 63 68 20 74 68 61 74 20 6d 75 74 65 78 65 73 20  ch that mutexes 
18c0: 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
18d0: 70 65 72 6d 61 6e 65 6e 74 6c 79 20 64 69 73 61  permanently disa
18e0: 62 6c 65 64 2e 20 3c 53 36 30 31 30 30 3e 0a 2a  bled. <S60100>.*
18f0: 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68  *.** {H10102} Th
1900: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1910: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1920: 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66  _threadsafe()] f
1930: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
1940: 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68      shall not ch
1950: 61 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20  ange when mutex 
1960: 73 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69  setting are modi
1970: 66 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20  fied at.**      
1980: 20 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e      runtime usin
1990: 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  g the [sqlite3_c
19a0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
19b0: 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20  ce and .**      
19c0: 20 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74      especially t
19d0: 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
19e0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1a00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1a10: 49 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54  ITHREAD], [SQLIT
1a20: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
1a30: 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ZED],.**        
1a40: 20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f    and [SQLITE_CO
1a50: 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62  NFIG_MUTEX] verb
1a60: 73 2e 20 3c 53 36 30 31 30 30 3e 0a 2a 2f 0a 69  s. <S60100>.*/.i
1a70: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
1a80: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
1a90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
1aa0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1ab0: 6e 20 48 61 6e 64 6c 65 20 7b 48 31 32 30 30 30  n Handle {H12000
1ac0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1ad0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ae0: 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63  ion} {database c
1af0: 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  onnections}.**.*
1b00: 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69  * Each open SQLi
1b10: 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72  te database is r
1b20: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
1b30: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1b40: 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65  stance of.** the
1b50: 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72   opaque structur
1b60: 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33  e named "sqlite3
1b70: 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c  ".  It is useful
1b80: 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20   to think of an 
1b90: 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74  sqlite3.** point
1ba0: 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e  er as an object.
1bb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f    The [sqlite3_o
1bc0: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1bd0: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a  _open16()], and.
1be0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
1bf0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1c00: 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72  s are its constr
1c10: 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c  uctors, and [sql
1c20: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a  ite3_close()].**
1c30: 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74   is its destruct
1c40: 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d  or.  There are m
1c50: 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66  any other interf
1c60: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
1c70: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c80: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
1c90: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
1ca0: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
1cb0: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1cc0: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
1cd0: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
1ce0: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
1cf0: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
1d00: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
1d10: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
1d20: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
1d30: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
1d40: 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30  teger Types {H10
1d50: 32 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200}.** KEYWORDS
1d60: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
1d70: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
1d80: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
1d90: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
1da0: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
1db0: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
1dc0: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
1dd0: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
1de0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
1df0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
1e00: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
1e10: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e20: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1e30: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
1e40: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
1e50: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
1e60: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
1e70: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
1e80: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
1e90: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
1ea0: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
1eb0: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
1ec0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1ed0: 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d 20 54 68  *.** {H10201} Th
1ee0: 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d  e [sqlite_int64]
1ef0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e   and [sqlite3_in
1f00: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1f10: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1f20: 20 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67      a 64-bit sig
1f30: 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f40: 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54 68 65 20  ** {H10202} The 
1f50: 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20  [sqlite_uint64] 
1f60: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e  and [sqlite3_uin
1f70: 74 36 34 5d 20 74 79 70 65 20 73 68 61 6c 6c 20  t64] type shall 
1f80: 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20  specify.**      
1f90: 20 20 20 20 61 20 36 34 2d 62 69 74 20 75 6e 73      a 64-bit uns
1fa0: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1fb0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1fc0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
1fd0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
1fe0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
1ff0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2000: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2010: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2020: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2030: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2040: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2050: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2060: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2070: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2080: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2090: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
20a0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
20b0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
20c0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
20d0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
20e0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
20f0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2100: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2110: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2120: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2130: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2140: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2150: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2160: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2170: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2180: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2190: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
21a0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
21b0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
21c0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
21d0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
21e0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
21f0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2200: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2210: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2220: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2230: 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30  Connection {H120
2240: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10}.**.** This r
2250: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65  outine is the de
2260: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
2270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2280: 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  t..**.** Applica
2290: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
22a0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
22b0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
22c0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22d0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
22e0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
22f0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2300: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
2310: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
2320: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2330: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
2340: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
2350: 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20   the object..** 
2360: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  The [sqlite3_nex
2370: 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66  t_stmt()] interf
2380: 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2390: 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a  to locate all.**
23a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23b0: 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65  ments] associate
23c0: 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
23d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
23e0: 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79  f desired..** Ty
23f0: 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74  pical code might
2400: 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a   look like this:
2410: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2420: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69  te><pre>.** sqli
2430: 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b  te3_stmt *pStmt;
2440: 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d  .** while( (pStm
2450: 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74  t = sqlite3_next
2460: 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30  _stmt(db, 0))!=0
2470: 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20   ){.** &nbsp;   
2480: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2490: 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a  (pStmt);.** }.**
24a0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
24b0: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73  ote>.**.** If [s
24c0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
24d0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65  is invoked while
24e0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
24f0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74  s open,.** the t
2500: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75  ransaction is au
2510: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2520: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
2530: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2540: 20 7b 48 31 32 30 31 31 7d 20 41 20 73 75 63 63   {H12011} A succ
2550: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
2560: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2570: 5d 20 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20  ] shall destroy 
2580: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2590: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25a0: 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a  tion] object C..
25b0: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41  **.** {H12012} A
25c0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
25d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
25e0: 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74  se(C)] shall ret
25f0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  urn SQLITE_OK..*
2600: 2a 0a 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20  *.** {H12013} A 
2610: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2620: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
2630: 65 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65  e(C)] shall rele
2640: 61 73 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ase all.**      
2650: 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73      memory and s
2660: 79 73 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20  ystem resources 
2670: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2680: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2690: 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20  tion].**        
26a0: 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30    C..**.** {H120
26b0: 31 34 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  14} A call to [s
26c0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
26d0: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
26e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68  connection] C th
26f0: 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  at.**          h
2700: 61 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  as one or more o
2710: 70 65 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74  pen [prepared st
2720: 61 74 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20  atements] shall 
2730: 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20  fail with.**    
2740: 20 20 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45        an [SQLITE
2750: 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64  _BUSY] error cod
2760: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35  e..**.** {H12015
2770: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
2780: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77  ite3_close(C)] w
2790: 68 65 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c  here C is a NULL
27a0: 20 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a   pointer shall.*
27b0: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
27c0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a  n SQLITE_OK..**.
27d0: 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57 68 65 6e  ** {H12019} When
27e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
27f0: 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  C)] is invoked o
2800: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2810: 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20  nnection] C.**  
2820: 20 20 20 20 20 20 20 20 74 68 61 74 20 68 61 73          that has
2830: 20 61 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73   a pending trans
2840: 61 63 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e  action, the tran
2850: 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65  saction shall be
2860: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 6c  .**          rol
2870: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
2880: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
2890: 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54 68 65 20  ** {A12016} The 
28a0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
28b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
28c0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
28d0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20   a NULL.**      
28e0: 20 20 20 20 70 6f 69 6e 74 65 72 20 6f 72 20 61      pointer or a
28f0: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
2900: 63 74 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69  ct pointer previ
2910: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 0a 2a  ously obtained.*
2920: 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
2930: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2940: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2950: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  6()], or.**     
2960: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
2970: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
2980: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
2990: 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
29a0: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
29b0: 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  3 *);../*.** The
29c0: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
29d0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
29e0: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
29f0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
2a00: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
2a10: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
2a20: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2a30: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
2a40: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
2a50: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
2a60: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
2a70: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
2a80: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
2a90: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
2aa0: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
2ab0: 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 31 30  Interface {H1210
2ac0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
2ad0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2ae0: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
2af0: 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e  nient way of run
2b00: 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ning one or more
2b10: 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2b20: 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ts without havin
2b30: 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74  g to write a lot
2b40: 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65   of C code.  The
2b50: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a   UTF-8 encoded.*
2b60: 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
2b70: 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61   are passed in a
2b80: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
2b90: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2ba0: 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65  3_exec()..** The
2bb0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2bc0: 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79  evaluated one by
2bd0: 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65   one until eithe
2be0: 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a  r an error or.**
2bf0: 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73   an interrupt is
2c00: 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72   encountered, or
2c10: 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20   until they are 
2c20: 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33  all done.  The 3
2c30: 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  rd parameter.** 
2c40: 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63  is an optional c
2c50: 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20  allback that is 
2c60: 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
2c70: 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79   each row of any
2c80: 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74   query.** result
2c90: 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68  s produced by th
2ca0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2cb0: 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
2cc0: 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65  eter tells where
2cd0: 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79  .** to write any
2ce0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e   error messages.
2cf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72  .**.** The error
2d00: 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20   message passed 
2d10: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
2d20: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69   5th parameter i
2d30: 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d  s held.** in mem
2d40: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2d50: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2d60: 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20  c()].  To avoid 
2d70: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a  a memory leak,.*
2d80: 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70  * the calling ap
2d90: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
2da0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
2db0: 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72  ree()] on any er
2dc0: 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72  ror.** message r
2dd0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
2de0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2df0: 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
2e00: 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nished using.** 
2e10: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
2e20: 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  e..**.** If the 
2e30: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
2e40: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2e50: 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  er is NULL or an
2e60: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a   empty string.**
2e70: 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   or a string con
2e80: 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69  taining only whi
2e90: 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d  tespace and comm
2ea0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
2eb0: 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  L.** statements 
2ec0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
2ed0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  d the database i
2ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
2ef0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f00: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
2f10: 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
2f20: 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20   in terms of.** 
2f30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2f50: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2f60: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f70: 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  )]..** The sqlit
2f80: 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e  e3_exec() routin
2f90: 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74  e does nothing t
2fa0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  o the database t
2fb0: 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f  hat cannot be do
2fc0: 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ne.** by [sqlite
2fd0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2fe0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ff0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3000: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  finalize()]..**.
3010: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
3020: 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41 20  *.** {H12101} A 
3030: 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
3040: 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
3050: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3060: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
3070: 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c 6c  hall sequentiall
3080: 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f  y evaluate all o
3090: 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  f the UTF-8 enco
30a0: 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ded,.**         
30b0: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
30c0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
30d0: 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
30e0: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
30f0: 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53 20         string S 
3100: 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65  within the conte
3110: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  xt of the [datab
3120: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3130: 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 32  D..**.** {H12102
3140: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3150: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3160: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3170: 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a  ] is NULL then.*
3180: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
3190: 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e  ctions of the in
31a0: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65  terface shall be
31b0: 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20   the same as if 
31c0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31d0: 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65  S parameter were
31e0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
31f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34 7d  ..**.** {H12104}
3200: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3210: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3220: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b  ec()] shall be [
3230: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c  SQLITE_OK] if al
3240: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  l.**          SQ
3250: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e  L statements run
3260: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e   successfully an
3270: 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  d to completion.
3280: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d 20  .**.** {H12105} 
3290: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
32a0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32b0: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e  c()] shall be an
32c0: 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   appropriate.** 
32d0: 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72           non-zer
32e0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
32f0: 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d  f any SQL statem
3300: 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  ent fails..**.**
3310: 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e 65   {H12107} If one
3320: 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20   or more of the 
3330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68  SQL statements h
3340: 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  anded to [sqlite
3350: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
3360: 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73        return res
3370: 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64  ults and the 3rd
3380: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3390: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20  t NULL, then.** 
33a0: 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
33b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
33c0: 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
33d0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68  3rd parameter sh
33e0: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
33f0: 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20     invoked once 
3400: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
3410: 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  result..**.** {H
3420: 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61  12110} If the ca
3430: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
3440: 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20   non-zero value 
3450: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
3460: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
3470: 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68    shall abort th
3480: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3490: 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  it is currently 
34a0: 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20  evaluating,.**  
34b0: 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c          skip all
34c0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
34d0: 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
34e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41  return [SQLITE_A
34f0: 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  BORT]..**.** {H1
3500: 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2113} The [sqlit
3510: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69  e3_exec()] routi
3520: 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74  ne shall pass it
3530: 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 4th parameter 
3540: 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20  through.**      
3550: 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70      as the 1st p
3560: 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
3570: 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
3580: 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71  {H12116} The [sq
3590: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
35a0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
35b0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35c0: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
35d0: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
35e0: 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
35f0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3600: 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a   current row of.
3610: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75  **          resu
3620: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31  lt..**.** {H1211
3630: 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
3640: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3650: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33 72  shall set the 3r
3660: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
3670: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
3680: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e  allback to be an
3690: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
36a0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f  rs to strings ho
36b0: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  lding the.**    
36c0: 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f 72        values for
36d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20   each column in 
36e0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73 75  the current resu
36f0: 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a  lt set row as.**
3700: 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
3710: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
3720: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
3730: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d 20  .**.** {H12122} 
3740: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3750: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3760: 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20 70  ll set the 4th p
3770: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
3780: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
3790: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72  back to be an ar
37a0: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
37b0: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  to strings holdi
37c0: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
37d0: 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75     names of resu
37e0: 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62  lt columns as ob
37f0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
3800: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3810: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3820: 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70  25} If the 3rd p
3830: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3840: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3850: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3860: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3870: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69 6c  xec()] shall sil
3880: 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71 75  ently discard qu
3890: 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a 0a  ery results..**.
38a0: 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20 61  ** {H12131} If a
38b0: 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
38c0: 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20  hile parsing or 
38d0: 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f  evaluating any o
38e0: 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  f the SQL.**    
38f0: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
3900: 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65   in the S parame
3910: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
3920: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3930: 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20   and if.**      
3940: 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65      the E parame
3950: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
3960: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3970: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f  xec()] shall sto
3980: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  re.**          i
3990: 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69  n *E an appropri
39a0: 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
39b0: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
39c0: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
39d0: 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
39e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
39f0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3a00: 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
3a10: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3a20: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3a30: 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  et the value of.
3a40: 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74  **          *E t
3a50: 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e  o NULL if E is n
3a60: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72  ot NULL and ther
3a70: 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e  e are no errors.
3a80: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d 20  .**.** {H12137} 
3a90: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3aa0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75  c(D,S,C,A,E)] fu
3ab0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
3ac0: 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65   the [error code
3ad0: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
3ae0: 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73  d message access
3af0: 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65  ible via [sqlite
3b00: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3b10: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3b20: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3b30: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3b40: 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g16()]..**.** {H
3b50: 31 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20  12138} If the S 
3b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3b70: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3b80: 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f  ,A,E)] is NULL o
3b90: 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
3ba0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
3bb0: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e   contains nothin
3bc0: 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
3bd0: 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74  tespace, comment
3be0: 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s,.**          a
3bf0: 6e 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73  nd/or semicolons
3c00: 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f  , then results o
3c10: 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  f [sqlite3_errco
3c20: 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  de()],.**       
3c30: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d     [sqlite3_errm
3c40: 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  sg()], and [sqli
3c50: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a  te3_errmsg16()].
3c60: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
3c70: 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63  l reset to indic
3c80: 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a  ate no errors..*
3c90: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
3ca0: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d  :.**.** {A12141}
3cb0: 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
3cc0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3cd0: 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65  _exec()] must be
3ce0: 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70   an valid and op
3cf0: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3d10: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ion]..**.** {A12
3d20: 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73  142} The databas
3d30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
3d40: 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20  t not be closed 
3d50: 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  while.**        
3d60: 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28    [sqlite3_exec(
3d70: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  )] is running..*
3d80: 2a 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68  *.** {A12143} Th
3d90: 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
3da0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73  on should use [s
3db0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74  qlite3_free()] t
3dc0: 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20  o free.**       
3dd0: 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68     the memory th
3de0: 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65  at *errmsg is le
3df0: 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f  ft pointing at o
3e00: 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  nce the error.**
3e10: 20 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67            messag
3e20: 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  e is no longer n
3e30: 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  eeded..**.** {A1
3e40: 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74  2145} The SQL st
3e50: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20  atement text in 
3e60: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3e70: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
3e80: 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ec()].**        
3e90: 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e    must remain un
3ea0: 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73  changed while [s
3eb0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69  qlite3_exec()] i
3ec0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
3ed0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3ee0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3f10: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3f20: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3f30: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f50: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3f60: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3f70: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3f80: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3f90: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3fa0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3fb0: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3fe0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3ff0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
4000: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
4030: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
4040: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
4050: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
4060: 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 0a   Codes {H10210}.
4070: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4080: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4090: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
40a0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
40b0: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
40c0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
40d0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
40e0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
40f0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4100: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
4110: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4120: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4130: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4140: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4150: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4160: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4170: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4180: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4190: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
41a0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
41b0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41c0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
41d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
41e0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
41f0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
4200: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
4210: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4230: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4240: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4250: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4260: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4270: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4280: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4290: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
42a0: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
42b0: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
42c0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
42d0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
42e0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
42f0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4300: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4310: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4320: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4330: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4340: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4350: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4360: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4370: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4380: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4390: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
43a0: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
43b0: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
43c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
43d0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
43e0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
43f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4400: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4410: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4420: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4430: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4450: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4460: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4470: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4480: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
44b0: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
44c0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
44d0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
44e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
44f0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4500: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4510: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4520: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4540: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4550: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4560: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4580: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4590: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
45a0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
45b0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
45e0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
45f0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4600: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4610: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4620: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4630: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4640: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4650: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4660: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4670: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4680: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
46a0: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
46b0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
46c0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
46d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
46e0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
46f0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4700: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4710: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4720: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4730: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4740: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4750: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4770: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4780: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4790: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
47a0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
47b0: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
47c0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
47d0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
47e0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
47f0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4800: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4810: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4820: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4830: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4840: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4850: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4870: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4880: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4890: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
48a0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
48b0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
48c0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
48d0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
48e0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
48f0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4900: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4910: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4920: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4930: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4940: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4950: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4960: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4970: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4980: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
49a0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
49b0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
49c0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
49d0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
49e0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
49f0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
4a00: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
4a10: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4a20: 32 32 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  220}.** KEYWORDS
4a30: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4a40: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
4a50: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
4a60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a80: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  e} {extended res
4a90: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
4aa0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
4ab0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
4ac0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
4ad0: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
4ae0: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
4af0: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
4b00: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4b10: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4b20: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4b30: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4b40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4b50: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4b60: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4b70: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4b80: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4b90: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4ba0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4bb0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4bc0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4bd0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4be0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4bf0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4c00: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4c10: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4c20: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4c30: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4c40: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4c50: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4c60: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4c70: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e  rrors. The exten
4c80: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4c90: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4ca0: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61  disabled.** on a
4cb0: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f   per database co
4cc0: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75  nnection basis u
4cd0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4ce0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4cf0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
4d00: 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66  I..**.** Some of
4d10: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
4d20: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d30: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
4d40: 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79  here..** One may
4d50: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62   expect the numb
4d60: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72  er of extended r
4d70: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c  esult codes will
4d80: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76   be expand.** ov
4d90: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61  er time.  Softwa
4da0: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74  re that uses ext
4db0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4dc0: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74  es should expect
4dd0: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72  .** to see new r
4de0: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66  esult codes in f
4df0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
4e00: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4e10: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65  The SQLITE_OK re
4e20: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e  sult code will n
4e30: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64  ever be extended
4e40: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79  .  It will alway
4e50: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20  s.** be exactly 
4e60: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  zero..**.** INVA
4e70: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
4e80: 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f  10223} The symbo
4e90: 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20  lic name for an 
4ea0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4eb0: 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61  code shall conta
4ec0: 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
4ed0: 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72  a related primar
4ee0: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73  y result code as
4ef0: 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a   a prefix..**.**
4f00: 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d 61 72   {H10224} Primar
4f10: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  y result code na
4f20: 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  mes shall contai
4f30: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
4f40: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
4f50: 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {H10225} Extende
4f60: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
4f70: 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  mes shall contai
4f80: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
4f90: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
4fa0: 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54 68 65  .** {H10226} The
4fb0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4fc0: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20  sult code shall 
4fe0: 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20  contain the.**  
4ff0: 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20          numeric 
5000: 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72  value of its cor
5010: 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61  responding prima
5020: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69  ry result code i
5030: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
5040: 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  s least signific
5050: 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23  ant 8 bits..*/.#
5060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5070: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5080: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5090: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
50a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
50b0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
50c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50d0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
50e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50f0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5100: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5110: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
5120: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5130: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5140: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5150: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5160: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5170: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5180: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5190: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
51a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
51b0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
51c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51d0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
51e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51f0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5200: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5210: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5230: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5250: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5260: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5270: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5290: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
52b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
52d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
52f0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5300: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
5310: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5320: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5330: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5340: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5350: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5360: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5370: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5380: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5390: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
53b0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
53c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
53d0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
53e0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
53f0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5400: 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 0a 2a  tions {H10230}.*
5410: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
5420: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
5430: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
5440: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
5450: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5460: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
5470: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
5480: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5490: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
54a0: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
54b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
54c0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
54d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
54e0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
54f0: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5500: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5510: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
5520: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
5540: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5550: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
5560: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5570: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5580: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5590: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
55a0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
55b0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
55c0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
55d0: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
55e0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5600: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5610: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5620: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5630: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5640: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
5650: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5660: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
5670: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69  0x00000800.#defi
5680: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5690: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
56a0: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
56b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
56c0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
56d0: 30 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69  0x00002000.#defi
56e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
56f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5700: 30 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69  0x00004000.#defi
5710: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
5720: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
5730: 30 78 30 30 30 30 38 30 30 30 0a 0a 2f 2a 0a 2a  0x00008000../*.*
5740: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5750: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5760: 63 73 20 7b 48 31 30 32 34 30 7d 0a 2a 2a 0a 2a  cs {H10240}.**.*
5770: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70  * The xDeviceCap
5780: 61 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64  abilities method
5790: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
57a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
57b0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
57c0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
57d0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
57e0: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
57f0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
5800: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
5810: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
5820: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
5830: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
5840: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
5850: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5860: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
5870: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
5880: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5890: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
58a0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
58b0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
58c0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
58d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
58e0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
58f0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
5900: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
5910: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
5920: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
5930: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
5940: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
5950: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
5960: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
5970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
5980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5990: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
59a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
59b0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
59c0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
59d0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
59e0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
59f0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
5a00: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
5a10: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
5a20: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
5a30: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
5a40: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
5a50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5a60: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
5a70: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
5a80: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
5a90: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
5aa0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
5ab0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5ad0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5ae0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
5af0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
5b00: 31 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30  12       0x00000
5b10: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5b20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5b30: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5b40: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5b60: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5b70: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5b80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5b90: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5ba0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5bb0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
5bc0: 4b 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  K        0x00000
5bd0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
5be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5bf0: 36 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  6K       0x00000
5c00: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
5c10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
5c20: 32 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  2K       0x00000
5c30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
5c50: 34 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30  4K       0x00000
5c60: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5c70: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5c80: 50 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30  PEND     0x00000
5c90: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
5ca0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5cb0: 49 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30  IAL      0x00000
5cc0: 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  400../*.** CAPI3
5cd0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5ce0: 67 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30  g Levels {H10250
5cf0: 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
5d00: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
5d10: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
5d20: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
5d30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
5d40: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
5d50: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
5d60: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
5d70: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
5d80: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5d90: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
5da0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
5db0: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
5dc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5dd0: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
5de0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
5df0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
5e00: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
5e10: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
5e20: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
5e30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
5e40: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
5e50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
5e60: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
5e70: 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36  ype Flags {H1026
5e80: 30 7d 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  0}.**.** When SQ
5e90: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
5ea0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
5eb0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
5ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5ed0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
5ee0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
5ef0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5f00: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5f10: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
5f20: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
5f30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
5f40: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
5f50: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
5f60: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
5f70: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
5f80: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
5f90: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
5fa0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
5fb0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
5fc0: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c  flushed. The SQL
5fd0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
5fe0: 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  flag means.** to
5ff0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
6000: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54  c() semantics. T
6010: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  he SQLITE_SYNC_F
6020: 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a  ULL flag means.*
6030: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d  * to use Mac OS-
6040: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6050: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
6060: 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  c()..*/.#define 
6070: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6080: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6090: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
60a0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
60b0: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
60c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
60d0: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
60e0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
60f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6100: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
6110: 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 0a 2a 2a  ndle {H11110}.**
6120: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6130: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6140: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6150: 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a  file in the OS.*
6160: 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  * interface laye
6170: 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  r.  Individual O
6180: 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c  S interface impl
6190: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
61a0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
61b0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
61c0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
61d0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
61e0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
61f0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
6200: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
6210: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
6220: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6230: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
6240: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
6250: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
6260: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
6270: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
6280: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
6290: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
62a0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
62b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
62c0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
62d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
62e0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
62f0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
6300: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
6310: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
6320: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6330: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
6340: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
6350: 20 7b 48 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20   {H11120}.**.** 
6360: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6370: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6380: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
6390: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
63a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
63b0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
63c0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
63d0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
63e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
63f0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6400: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6410: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6420: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6430: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6440: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6450: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6460: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6470: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6480: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6490: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
64a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
64b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
64c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
64d0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
64e0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
64f0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6500: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6510: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6520: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6530: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6540: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
6550: 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c   a Mac OS-X styl
6560: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
6570: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
6580: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
6590: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
65a0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
65b0: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
65c0: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
65d0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
65e0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
65f0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6600: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6610: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6620: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6630: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6640: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6650: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
6660: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6670: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6680: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
6690: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
66a0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
66b0: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
66c0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
66d0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
66e0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
66f0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6700: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6710: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6720: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6730: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6740: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6750: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6760: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6770: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6780: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6790: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
67a0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
67b0: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
67c0: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
67d0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
67e0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
67f0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6800: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6810: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6820: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6830: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6840: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6850: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6860: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6870: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6880: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6890: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
68a0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
68b0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
68c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
68d0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
68e0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
68f0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6900: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6910: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6920: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6930: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6940: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6950: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6960: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6970: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6980: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6990: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
69a0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
69b0: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
69c0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
69d0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
69e0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
69f0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6a00: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6a10: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6a20: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6a30: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6a40: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6a50: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6a60: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6a70: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6a80: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6a90: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6aa0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6ab0: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6ac0: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6ad0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6ae0: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6af0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6b00: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6b10: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6b20: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6b30: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6b40: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6b50: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6b60: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6b70: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6b80: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6b90: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ba0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6bb0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6bc0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6bd0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6be0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6bf0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6c00: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6c10: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6c20: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6c30: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6c40: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6c50: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6c60: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6c70: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6c80: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6c90: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ca0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6cb0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6cc0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6cd0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6ce0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6cf0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6d10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
6d30: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
6d50: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
6d70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
6d90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6da0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6db0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6dc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
6dd0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6de0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6df0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6e00: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6e10: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
6e20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6e30: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
6e40: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
6e50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6e60: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6e70: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6e80: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6e90: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6eb0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
6ec0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6ed0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6ee0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6ef0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6f00: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6f10: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6f20: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6f30: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6f40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6f50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6f60: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6f70: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6f80: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6f90: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6fa0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6fb0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
6fc0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6fd0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6fe0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6ff0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7000: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7010: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7020: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7030: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7040: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
7050: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
7060: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
7070: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
7080: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
7090: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70a0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70b0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
70c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
70d0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
70e0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
70f0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7100: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7110: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7120: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7130: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7140: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7150: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
7160: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
7170: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7180: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7190: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71a0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71b0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
71c0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
71d0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
71e0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
71f0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7200: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7210: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7220: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7230: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7240: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7250: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
7260: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7270: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
7280: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
72c0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
72d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
72e0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
72f0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7300: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7310: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7320: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7330: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7340: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7350: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
7360: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
7370: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
7380: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7390: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73a0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b  ontrol Opcodes {
73b0: 48 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  H11310}.**.** Th
73c0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
73d0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
73e0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
73f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7400: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7410: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7420: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
7430: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7440: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
7450: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
7460: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7470: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
7480: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7490: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
74a0: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
74b0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
74c0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
74d0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
74e0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
74f0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7500: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7510: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7520: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
7530: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
7540: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7550: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7560: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7570: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7580: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7590: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
75a0: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
75b0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
75c0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
75d0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
75e0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
75f0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7600: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7620: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7630: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
7640: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
7650: 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d   Handle {H17110}
7660: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
7670: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
7680: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
7690: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
76a0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
76b0: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
76c0: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
76d0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
76e0: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
76f0: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
7700: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
7710: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7720: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
7730: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
7740: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
7750: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
7760: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
7770: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
7780: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
7790: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
77a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
77b0: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
77c0: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
77d0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
77e0: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48  erface Object {H
77f0: 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11140}.**.** An 
7800: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7810: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7820: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7830: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7840: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7850: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7860: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
7870: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
7880: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
7890: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
78a0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
78b0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
78c0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
78d0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
78e0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
78f0: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
7900: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
7910: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
7920: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
7930: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
7940: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
7950: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
7960: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
7970: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
7980: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
7990: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
79a0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
79b0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
79c0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
79d0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
79e0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
79f0: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
7a00: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
7a10: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
7a20: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
7a30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
7a40: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
7a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
7a60: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
7a70: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
7a80: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
7a90: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7aa0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7ab0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7ac0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7ad0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7ae0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7af0: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7b00: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7b10: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7b20: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7b30: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
7b40: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
7b50: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
7b60: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
7b70: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
7b80: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
7b90: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7ba0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7bb0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7bc0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7bd0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7be0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7bf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7c00: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7c10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7c20: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7c30: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
7c40: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
7c50: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
7c60: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
7c70: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
7c80: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
7c90: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
7ca0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
7cb0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
7cc0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
7cd0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
7ce0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
7cf0: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
7d00: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
7d10: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
7d20: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
7d30: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
7d40: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
7d50: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
7d60: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
7d70: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
7d80: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
7d90: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7da0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
7db0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
7dc0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
7dd0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
7de0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53  **.** {H11141} S
7df0: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
7e00: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
7e10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
7e20: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
7e30: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
7e40: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
7e50: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
7e60: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
7e70: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68  ).  SQLite furth
7e80: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
7e90: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
7ea0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
7eb0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
7ec0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
7ed0: 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20  * called. {END} 
7ee0: 20 42 65 63 61 73 75 65 20 6f 66 20 74 68 65 20   Becasue of the 
7ef0: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73  previous sentens
7f00: 65 2c 20 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  e, .** the [sqli
7f10: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
7f20: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
7f30: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
7f40: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
7f50: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
7f60: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
7f70: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
7f80: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
7f90: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78  e parameter is x
7fa0: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
7fb0: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
7fc0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65  n.** must invite
7fd0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
7fe0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
7ff0: 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20  file.  Whenever 
8000: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
8010: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
8020: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
8030: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
8040: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
8050: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
8060: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8070: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
8080: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32  ]..**.** {H11142
8090: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
80a0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
80b0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
80c0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
80d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
80e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
80f0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
8100: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
8110: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8120: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8130: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8140: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8160: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8170: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8180: 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70   {END}.** If xOp
8190: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
81a0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
81b0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
81c0: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
81d0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
81e0: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
81f0: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
8200: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
8210: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53  **.** {H11143} S
8220: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
8230: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8240: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8250: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
8260: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
8270: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
8280: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
8290: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
82a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
82b0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
82c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
82d0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
82e0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
82f0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
8300: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8310: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
8320: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8330: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
8340: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8350: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
8360: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8370: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
8380: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75  _JOURNAL].** </u
8390: 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
83a0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
83b0: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
83c0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
83d0: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
83e0: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
83f0: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
8400: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
8410: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
8420: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
8430: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
8440: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
8450: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
8460: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
8470: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
8480: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
8490: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
84a0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
84b0: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
84c0: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
84d0: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
84e0: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
84f0: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
8500: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
8510: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
8520: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
8530: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
8540: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
8550: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
8560: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
8570: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
8580: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
8590: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
85a0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
85b0: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
85c0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
85d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
85e0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
85f0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
8600: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8610: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8620: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
8630: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
8640: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
8650: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20  .**.** {H11145} 
8660: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8670: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
8680: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
8690: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
86a0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
86b0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31   is closed.  {H1
86c0: 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54  1146} The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
86f0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64   set for TEMP  d
8700: 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61  atabases, journa
8710: 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f  ls and for subjo
8720: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urnals..**.** {H
8730: 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49  11147} The [SQLI
8740: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8750: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8760: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8770: 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65   opened.** for e
8780: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
8790: 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73    This flag is s
87a0: 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73  et for all files
87b0: 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74   except.** for t
87c0: 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
87d0: 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   file..**.** {H1
87e0: 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73  1148} At least s
87f0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8800: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8810: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
8820: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
8830: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
8840: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
8850: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
8860: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8870: 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f  n. {END}  The xO
8880: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
8890: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
88a0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
88b0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
88c0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
88d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d  ..**.** {H11149}
88e0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
88f0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
8900: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
8910: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
8920: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
8930: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
8940: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
8950: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8960: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
8970: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
8980: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8990: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
89a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
89b0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
89c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
89d0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
89e0: 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20  {END}  The file 
89f0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
8a00: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ctory..**.** {H1
8a10: 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c  1150} SQLite wil
8a20: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8a30: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8a40: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8a50: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8a60: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8a70: 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54  name. {H11151} T
8a80: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
8a90: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
8aa0: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
8ab0: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
8ac0: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
8ad0: 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20  hods. {END}  If 
8ae0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8af0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
8b00: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
8b10: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
8b20: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
8b30: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
8b40: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
8b50: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
8b60: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
8b70: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
8b80: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
8b90: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
8ba0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
8bb0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
8bc0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
8bd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
8be0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
8bf0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
8c00: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
8c10: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
8c20: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
8c30: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
8c40: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
8c50: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
8c60: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
8c70: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
8c80: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
8c90: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
8ca0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
8cb0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
8cc0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
8cd0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
8ce0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
8cf0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
8d00: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
8d10: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
8d20: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
8d30: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
8d40: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
8d50: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
8d60: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
8d70: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
8d80: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
8d90: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
8da0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
8db0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8dc0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
8dd0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
8de0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
8df0: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
8e00: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8e10: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
8e20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8e30: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
8e40: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
8e50: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
8e60: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
8e70: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
8e80: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
8e90: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
8ea0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
8eb0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
8ec0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
8ed0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
8ee0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
8ef0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
8f00: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
8f10: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
8f20: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
8f30: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
8f40: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
8f50: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
8f60: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
8f70: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
8f80: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
8f90: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
8fa0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
8fb0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
8fc0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8fd0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
8fe0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
8ff0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
9000: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
9010: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
9020: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
9030: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9040: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
9050: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
9060: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
9070: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9080: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
9090: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
90a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
90b0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
90c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
90d0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
90e0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
90f0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
9100: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
9110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9120: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
9130: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
9140: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
9150: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
9160: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28  rMsg);.  void *(
9170: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9180: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9190: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
91a0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
91b0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
91c0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
91d0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
91e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
91f0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
9200: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
9210: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
9220: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
9230: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
9240: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
9250: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
9260: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
9270: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
9280: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
9290: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
92a0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
92b0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
92c0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
92d0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
92e0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
92f0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
9300: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
9310: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9320: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
9330: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
9340: 68 6f 64 20 7b 48 31 31 31 39 30 7d 0a 2a 2a 0a  hod {H11190}.**.
9350: 2a 2a 20 7b 48 31 31 31 39 31 7d 20 54 68 65 73  ** {H11191} Thes
9360: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9370: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
9380: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
9390: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
93a0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
93b0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
93c0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
93d0: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
93e0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
93f0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
9400: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9410: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
9420: 0a 2a 2a 20 7b 48 31 31 31 39 32 7d 20 57 69 74  .** {H11192} Wit
9430: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
9440: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
9450: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
9460: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
9470: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
9480: 73 74 73 2e 0a 2a 2a 20 7b 48 31 31 31 39 33 7d  sts..** {H11193}
9490: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
94a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
94b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
94c0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
94d0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
94e0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
94f0: 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b  d writable..** {
9500: 48 31 31 31 39 34 7d 20 57 69 74 68 20 53 51 4c  H11194} With SQL
9510: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
9520: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9530: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9540: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9550: 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23  s readable..*/.#
9560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9570: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
9580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9590: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
95a0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
95b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
95c0: 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     2../*.** CAPI
95d0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
95e0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
95f0: 61 72 79 20 7b 48 31 30 31 33 30 7d 0a 2a 2a 0a  ary {H10130}.**.
9600: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
9610: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9620: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
9630: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
9640: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
9650: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
9660: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
9670: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
9680: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
9690: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
96a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
96b0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
96c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
96d0: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
96e0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
96f0: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
9700: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9720: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
9730: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
9740: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
9750: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
9760: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
9770: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9780: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
9790: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
97a0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
97b0: 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66  n().  Only an ef
97c0: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
97d0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
97e0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
97f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
9800: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
9810: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
9820: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
9830: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
9840: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  gs, sqlite3_init
9850: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69  ialize() shall i
9860: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
9870: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
9880: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f  ilarly, sqlite3_
9890: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68  shutdown().** sh
98a0: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  all invoke sqlit
98b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
98c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
98d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
98e0: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
98f0: 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73  TE_OK on success
9900: 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65  ..** If for some
9910: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
9920: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9930: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
9940: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
9950: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
9960: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
9970: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
9980: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
9990: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
99a0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
99b0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
99c0: 61 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  an SQLITE_OK..**
99d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
99e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
99f0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
9a00: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
9a10: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
9a20: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
9a30: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
9a40: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
9a50: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
9a60: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
9a70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
9a80: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
9a90: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
9aa0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
9ab0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ac0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
9ad0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
9ae0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
9af0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
9b00: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
9b10: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
9b20: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
9b30: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
9b40: 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c  ready.  However,
9b50: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
9b60: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
9b70: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
9b80: 49 4e 49 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  INIT.** compile-
9b90: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
9ba0: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
9bb0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
9bc0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
9bd0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
9be0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9bf0: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
9c00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9c10: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
9c20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
9c30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9c40: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
9c50: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
9c60: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
9c70: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
9c80: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
9c90: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
9ca0: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
9cb0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
9cc0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
9cd0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9ce0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
9cf0: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
9d00: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
9d10: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
9d20: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
9d30: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
9d40: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
9d50: 69 6c 65 64 20 77 69 74 68 20 53 51 4c 49 54 45  iled with SQLITE
9d60: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d  _OMIT_AUTOINIT m
9d70: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
9d80: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
9d90: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
9da0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
9db0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
9dc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9dd0: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
9de0: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
9df0: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
9e00: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
9e10: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
9e20: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
9e30: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
9e40: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
9e50: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
9e60: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
9e70: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
9e80: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
9e90: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
9ea0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
9eb0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
9ec0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
9ed0: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
9ee0: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
9ef0: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
9f00: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
9f10: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
9f20: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
9f30: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
9f40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
9f50: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
9f60: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
9f70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
9f80: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
9f90: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
9fa0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
9fb0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
9fc0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
9fd0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
9fe0: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
9ff0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
a000: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
a010: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a020: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
a030: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
a040: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
a050: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
a060: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a070: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
a080: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
a090: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
a0a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
a0b0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
a0c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
a0d0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a0e0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
a0f0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
a100: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
a110: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
a120: 70 69 6c 65 64 20 66 6f 72 20 75 6e 69 78 2c 20  piled for unix, 
a130: 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32  windows, or os/2
a140: 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69 6c 74 20  ..** When built 
a150: 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
a160: 72 6d 73 20 28 75 73 69 6e 67 20 74 68 65 20 53  rms (using the S
a170: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
a180: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
a190: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
a1a0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
a1b0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
a1c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
a1d0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
a1e0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
a1f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
a200: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
a210: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
a220: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
a230: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
a240: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a250: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
a260: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
a270: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
a280: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
a290: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
a2a0: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
a2b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
a2c0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a2d0: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
a2e0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
a2f0: 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
a300: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
a310: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
a320: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
a330: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
a340: 72 61 72 79 20 7b 48 31 30 31 34 35 7d 0a 2a 2a  rary {H10145}.**
a350: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a360: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a370: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a380: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
a390: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a3a0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
a3b0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
a3c0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
a3d0: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
a3e0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a3f0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
a400: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
a410: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
a420: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
a430: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
a440: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
a450: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
a460: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
a470: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
a480: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
a490: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
a4a0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
a4b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a4c0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
a4d0: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
a4e0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
a4f0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
a500: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
a510: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
a520: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
a530: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
a540: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
a550: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
a560: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
a570: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a580: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
a590: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
a5a0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
a5b0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
a5c0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
a5d0: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
a5e0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
a5f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
a600: 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  ]..** Note, howe
a610: 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65  ver, that sqlite
a620: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
a630: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
a640: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
a650: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
a660: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
a670: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
a680: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
a690: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
a6a0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
a6b0: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
a6c0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
a6d0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a6e0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
a6f0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
a700: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
a710: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
a720: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
a730: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
a740: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
a750: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
a760: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
a770: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
a780: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
a790: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
a7a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
a7b0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
a7c0: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
a7d0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
a7e0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
a7f0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
a800: 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  E_OK..** If the 
a810: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
a820: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
a830: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
a840: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
a850: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
a860: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
a870: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
a880: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a890: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a8a0: 63 65 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ce is considered
a8b0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
a8c0: 20 74 68 61 74 0a 2a 2a 20 6e 65 77 20 63 6f 6e   that.** new con
a8d0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a8e0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
a8f0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
a900: 65 73 20 61 6e 64 20 65 78 69 73 74 69 6e 67 0a  es and existing.
a910: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
a920: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
a930: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
a940: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2f 0a 69 6e 74  modified..*/.int
a950: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a960: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
a970: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
a980: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
a990: 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 0a  utines {H10155}.
a9a0: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
a9b0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
a9c0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
a9d0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
a9e0: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
a9f0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
aa00: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
aa10: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
aa20: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
aa30: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
aa40: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
aa50: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
aa60: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
aa70: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
aa80: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
aa90: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
aaa0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
aab0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
aac0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
aad0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
aae0: 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61  ALLOC].  By crea
aaf0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
ab00: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
ab10: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
ab20: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
ab30: 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63  nfig()] during c
ab40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
ab50: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
ab60: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
ab70: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
ab80: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
ab90: 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51  system.** for SQ
aba0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
abb0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
abc0: 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
abd0: 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
abe0: 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
abf0: 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65  th a built-in me
ac00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
ac10: 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63  hat is.** perfec
ac20: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
ac30: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
ac40: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
ac50: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
ac60: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
ac70: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
ac80: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
ac90: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
aca0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
acb0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
acc0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
acd0: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
ace0: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
acf0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
ad00: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
ad10: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
ad20: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ad30: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
ad40: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
ad50: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
ad60: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
ad70: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
ad80: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
ad90: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
ada0: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
adb0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
adc0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
add0: 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e  alloc, xFree, an
ade0: 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f  d xRealloc metho
adf0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
ae00: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
ae10: 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72  ), free(), and r
ae20: 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f  ealloc() functio
ae30: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
ae40: 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  dard library..**
ae50: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
ae60: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
ae70: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
ae80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ae90: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
aea0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
aeb0: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
aec0: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
aed0: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
aee0: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
aef0: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
af00: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
af10: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
af20: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
af30: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
af40: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
af50: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
af60: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
af70: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
af80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
af90: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
afa0: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
afb0: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
afc0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
afd0: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
afe0: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
aff0: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
b000: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
b010: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
b020: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
b030: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
b040: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
b050: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
b060: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b070: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
b080: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
b090: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
b0a0: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
b0b0: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
b0c0: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
b0d0: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
b0e0: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
b0f0: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
b100: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
b110: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b120: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
b130: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
b140: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
b150: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
b160: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
b170: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
b180: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
b190: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
b1a0: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74   xShutdown..*/.t
b1b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
b1c0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b1d0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
b1e0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
b1f0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
b200: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
b210: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
b220: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
b230: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
b240: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
b250: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
b260: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
b270: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
b280: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
b290: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
b2a0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
b2b0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
b2c0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
b2d0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b2e0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
b2f0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
b300: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
b310: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
b320: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
b330: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
b340: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
b350: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
b360: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
b370: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
b380: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
b390: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
b3a0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
b3b0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
b3c0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
b3d0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b3e0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
b3f0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
b400: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
b410: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
b420: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
b430: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
b440: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
b450: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48  ation Options {H
b460: 31 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10160}.**.** The
b470: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
b480: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
b490: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
b4a0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
b4b0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
b4c0: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
b4d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
b4e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b4f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
b500: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
b510: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
b520: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
b530: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
b540: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
b550: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
b560: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
b570: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
b580: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
b590: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
b5a0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
b5b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
b5c0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
b5d0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
b5e0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
b5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b600: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
b610: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
b620: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
b630: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
b640: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
b650: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
b660: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
b670: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
b680: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
b690: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b6a0: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
b6b0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
b6c0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
b6d0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
b6e0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
b6f0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
b700: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
b710: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
b720: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
b730: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
b740: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
b750: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b760: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
b770: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
b780: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
b790: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
b7a0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
b7b0: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
b7c0: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
b7d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b7e0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
b7f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
b800: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
b810: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
b820: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
b830: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
b840: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
b850: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
b860: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b870: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
b880: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
b890: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
b8a0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
b8b0: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
b8c0: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
b8d0: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
b8e0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b8f0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
b900: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
b910: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
b920: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
b930: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
b940: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
b950: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
b960: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
b970: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
b980: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
b990: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
b9a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
b9b0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
b9c0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
b9d0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
b9e0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
b9f0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ba00: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
ba10: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
ba20: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
ba30: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
ba40: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
ba50: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
ba60: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
ba70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ba80: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
ba90: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
baa0: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
bab0: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
bac0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
bad0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
bae0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
baf0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
bb00: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
bb10: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   time..**.** <p>
bb20: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
bb30: 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79  on option merely
bb40: 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75 6c   sets the defaul
bb50: 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61  t mutex .** beha
bb60: 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a  vior to serializ
bb70: 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74  e access to [dat
bb80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bb90: 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a  s].  Individual.
bba0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
bbb0: 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76  nections] can ov
bbc0: 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74 74  erride this sett
bbd0: 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ing.** using the
bbe0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
bbf0: 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b  MUTEX] flag to [
bc00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
bc10: 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a  )].</p></dd>.**.
bc20: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bc30: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
bc40: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
bc50: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
bc60: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
bc70: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
bc80: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
bc90: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
bca0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
bcb0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
bcc0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
bcd0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
bce0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
bcf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
bd00: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
bd10: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
bd20: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bd30: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
bd40: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
bd50: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bd60: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
bd70: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
bd80: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bd90: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
bda0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
bdb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
bdc0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
bdd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
bde0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
bdf0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
be00: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
be10: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
be20: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
be30: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
be40: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
be50: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
be60: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
be70: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
be80: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
be90: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bea0: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
beb0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
bec0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
bed0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bee0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
bef0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
bf00: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
bf10: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bf20: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
bf30: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
bf40: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bf50: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f  takes single boo
bf60: 6c 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68  lean argument wh
bf70: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
bf80: 69 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63  isables.** the c
bf90: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
bfa0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
bfb0: 74 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e  tatistics.  When
bfc0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a   disabled, the.*
bfd0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
bfe0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
bff0: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
c000: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
c010: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c020: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
c030: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
c040: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
c050: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
c060: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
c070: 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a  _heap_limit()].*
c080: 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33  *   <li> sqlite3
c090: 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29  _memory_status()
c0a0: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c0b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c0c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c0d0: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c0e0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c0f0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c100: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c110: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c120: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c130: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c140: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c150: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c160: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
c170: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c180: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
c190: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
c1a0: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
c1b0: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c1c0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c1d0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c1e0: 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a   16. The first.*
c1f0: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
c200: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
c210: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
c220: 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79  east (sz+4)*N by
c230: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
c240: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  * SQLite will us
c250: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e no more than o
c260: 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
c270: 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68  r at once per th
c280: 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68  read, so.** N sh
c290: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
c2a0: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
c2b0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
c2c0: 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a  reads.  The sz.*
c2d0: 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  * parameter shou
c2e0: 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68  ld be 6 times th
c2f0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
c300: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
c310: 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72  age size..** Scr
c320: 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65  atch buffers are
c330: 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66   used as part of
c340: 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   the btree balan
c350: 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49  ce operation.  I
c360: 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62  f.** The btree b
c370: 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64  alancer needs ad
c380: 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
c390: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
c3a0: 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63  rovided by.** sc
c3b0: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72  ratch buffers or
c3c0: 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62   if no scratch b
c3d0: 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73  uffer space is s
c3e0: 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53  pecified, then S
c3f0: 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f  QLite.** goes to
c400: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c410: 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  ()] to obtain th
c420: 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64  e memory it need
c430: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
c440: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c450: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
c460: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
c470: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
c480: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
c490: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
c4a0: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
c4b0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
c4c0: 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72  cache.  There ar
c4d0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
c4e0: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
c4f0: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  the.** memory, t
c500: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
c510: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
c520: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
c530: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
c540: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
c550: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65  t must be a powe
c560: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
c570: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20   512 and 32768. 
c580: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
c590: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c5a0: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
c5b0: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
c5c0: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20   (sz+4)*N bytes 
c5d0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
c5e0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
c5f0: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
c600: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
c610: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
c620: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
c630: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
c640: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
c650: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
c660: 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e  he.  If addition
c670: 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
c680: 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
c690: 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
c6a0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
c6b0: 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
c6c0: 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
c6d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c6e0: 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
c6f0: 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
c700: 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
c710: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c720: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
c730: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c740: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c750: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c760: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c770: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
c780: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
c790: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c7a0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
c7b0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
c7c0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
c7d0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
c7e0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
c7f0: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
c800: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
c810: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
c820: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c830: 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72  mory, the number
c840: 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
c850: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
c860: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
c870: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
c880: 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66  ze.  If.** the f
c890: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
c8a0: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
c8b0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
c8c0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
c8d0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
c8e0: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
c8f0: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
c900: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
c910: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
c920: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
c930: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
c940: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c950: 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65  MALLOC].  If the
c960: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
c970: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  er is not NULL a
c980: 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  nd either [SQLIT
c990: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
c9a0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
c9b0: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
c9c0: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
c9d0: 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
c9e0: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
c9f0: 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
ca00: 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
ca10: 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
ca20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
ca30: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
ca40: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ca50: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
ca60: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
ca70: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ca80: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ca90: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
caa0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
cab0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
cac0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cad0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
cae0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
caf0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
cb00: 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
cb10: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cb20: 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20  in place.** the 
cb30: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
cb40: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
cb50: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cb60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
cb70: 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
cb80: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
cb90: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
cba0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
cbb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cbc0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
cbd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
cbe0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
cbf0: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
cc00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
cc10: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
cc20: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
cc30: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
cc40: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
cc50: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
cc60: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
cc70: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
cc80: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
cc90: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
cca0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
ccb0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
ccc0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
ccd0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
cce0: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
ccf0: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
cd00: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a  xample.</dd>.*/.
cd10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cd20: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
cd30: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
cd40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cd50: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cd60: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
cd70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cd80: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
cd90: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
cda0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cdb0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
cdc0: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
cdd0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
cde0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
cdf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
ce00: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
ce10: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
ce20: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
ce30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
ce40: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
ce50: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
ce60: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
ce70: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
ce80: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
ce90: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
cea0: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
ceb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cec0: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
ced0: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
cee0: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
cef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cf00: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
cf10: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
cf20: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
cf30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
cf40: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
cf50: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
cf60: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
cf70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cf80: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
cf90: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
cfa0: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a  ex_methods* */..
cfb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cfc0: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
cfd0: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
cfe0: 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30  lt Codes {H12200
cff0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
d000: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
d010: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
d020: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
d030: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
d040: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
d050: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
d060: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
d070: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
d080: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
d090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
d0a0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
d0b0: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
d0c0: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
d0d0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
d0e0: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
d0f0: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
d100: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
d110: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
d120: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
d130: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
d140: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
d150: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
d160: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
d170: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
d180: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
d190: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
d1a0: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
d1b0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
d1c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
d1d0: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
d1e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
d1f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
d200: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
d210: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
d220: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
d230: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
d240: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
d250: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
d260: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
d270: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d280: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
d290: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 0a 2a 2a  owid {H12220}.**
d2a0: 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69  .** Each entry i
d2b0: 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
d2c0: 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
d2d0: 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
d2e0: 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
d2f0: 65 64 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20  ed the "rowid". 
d300: 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
d310: 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
d320: 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
d330: 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
d340: 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
d350: 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
d360: 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
d370: 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
d380: 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
d390: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
d3a0: 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c  . If.** the tabl
d3b0: 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
d3c0: 66 20 74 79 70 65 20 49 4e 54 45 47 45 52 20 50  f type INTEGER P
d3d0: 52 49 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20  RIMARY KEY then 
d3e0: 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
d3f0: 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
d400: 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
d410: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
d420: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f  e returns the ro
d430: 77 69 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  wid of the most 
d440: 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
d450: 73 66 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f  sful INSERT into
d460: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
d470: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
d480: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
d490: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
d4a0: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
d4b0: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73  ccessful INSERTs
d4c0: 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63  .** have ever oc
d4d0: 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64  curred on that d
d4e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d4f0: 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75  on, zero is retu
d500: 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  rned..**.** If a
d510: 6e 20 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20  n INSERT occurs 
d520: 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
d530: 2c 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64  , then the rowid
d540: 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
d550: 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
d560: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
d570: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
d580: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
d590: 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
d5a0: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
d5b0: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
d5c0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
d5d0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
d5e0: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
d5f0: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
d600: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
d610: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
d620: 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68  .** An INSERT th
d630: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
d640: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
d650: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
d660: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  ** successful IN
d670: 53 45 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f  SERT and does no
d680: 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
d690: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
d6a0: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
d6b0: 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20   Thus INSERT OR 
d6c0: 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
d6d0: 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
d6e0: 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
d6f0: 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
d700: 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
d710: 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
d720: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
d730: 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
d740: 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
d750: 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45  ails.  When INSE
d760: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
d770: 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
d780: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
d790: 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
d7a0: 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
d7b0: 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
d7c0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
d7d0: 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
d7e0: 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
d7f0: 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
d800: 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
d810: 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
d820: 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
d830: 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
d840: 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
d850: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  face..**.** For 
d860: 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
d870: 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
d880: 20 49 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69   INSERT is consi
d890: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
d8a0: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
d8b0: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
d8c0: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
d8d0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
d8e0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  TS:.**.** {H1222
d8f0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
d900: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d910: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
d920: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a  turns the rowid.
d930: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
d940: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
d950: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
d960: 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68   performed on th
d970: 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
d980: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
d990: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74  nection] and wit
d9a0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20  hin the same or 
d9b0: 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20  higher level.** 
d9c0: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
d9d0: 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
d9e0: 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 20  o if there have 
d9f0: 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69  been no qualifyi
da00: 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a  ng inserts..**.*
da10: 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b  * {H12223} The [
da20: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
da30: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
da40: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
da50: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61  e.**          sa
da60: 6d 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61  me value when ca
da70: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
da80: 6d 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  me trigger conte
da90: 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  xt.**          i
daa0: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
dab0: 65 20 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f  e and after a RO
dac0: 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53  LLBACK..**.** AS
dad0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
dae0: 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 73   {A12232} If a s
daf0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
db00: 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e  erforms a new IN
db10: 53 45 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65  SERT on the same
db20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
db30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
db40: 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
db50: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
db60: 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20  rowid()].**     
db70: 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73       function is
db80: 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
db90: 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
dba0: 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c  st insert rowid,
dbb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
dbc0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
dbd0: 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
dbe0: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
dbf0: 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  id()] is.**     
dc00: 20 20 20 20 20 75 6e 70 72 65 64 69 63 74 61 62       unpredictab
dc10: 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
dc20: 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
dc30: 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
dc40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73  .**          las
dc50: 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a  t insert rowid..
dc60: 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
dc70: 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
dc80: 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
dc90: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
dca0: 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
dcb0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
dcc0: 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30  Modified {H12240
dcd0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  }.**.** This fun
dce0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
dcf0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
dd00: 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
dd10: 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
dd20: 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
dd30: 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
dd40: 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
dd50: 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
dd60: 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
dd70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
dd80: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
dd90: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
dda0: 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61  ter..** Only cha
ddb0: 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
ddc0: 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
ddd0: 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
dde0: 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45  UPDATE,.** or DE
ddf0: 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
de00: 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
de10: 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
de20: 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
de30: 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75  gers are not cou
de40: 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  nted. Use the [s
de50: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
de60: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
de70: 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
de80: 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
de90: 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e  changes includin
dea0: 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  g changes caused
deb0: 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a   by triggers..**
dec0: 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67  .** A "row chang
ded0: 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
dee0: 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
def0: 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
df00: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
df10: 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
df20: 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
df30: 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
df40: 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
df50: 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
df60: 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
df70: 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
df80: 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
df90: 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
dfa0: 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20   DROP TABLE, or 
dfb0: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
dfc0: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
dfd0: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
dfe0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  t row changes..*
dff0: 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
e000: 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
e010: 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
e020: 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
e030: 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
e040: 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74 72  e script of a tr
e050: 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c  igger.  Most SQL
e060: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
e070: 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
e080: 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
e090: 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
e0a0: 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
e0b0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e0c0: 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
e0d0: 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
e0e0: 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
e0f0: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
e100: 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
e110: 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
e120: 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
e130: 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
e140: 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
e150: 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
e160: 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
e170: 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
e180: 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
e190: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
e1a0: 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
e1b0: 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
e1c0: 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
e1d0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  xt..**.** This f
e1e0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
e1f0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
e200: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
e210: 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
e220: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
e230: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
e240: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
e250: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
e260: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
e270: 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20  *.** Thus, when 
e280: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
e290: 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
e2a0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e2b0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
e2c0: 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
e2d0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e2e0: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e2f0: 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
e300: 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
e310: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
e320: 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
e330: 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
e340: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
e350: 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
e360: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
e370: 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
e380: 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
e390: 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
e3a0: 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
e3b0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
e3c0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
e3d0: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
e3e0: 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
e3f0: 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
e400: 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
e410: 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
e420: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
e430: 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
e440: 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
e450: 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
e460: 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
e470: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
e480: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
e490: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
e4a0: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
e4b0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
e4c0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
e4d0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
e4e0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
e4f0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
e500: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
e510: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
e520: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
e530: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
e540: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
e550: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
e560: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
e570: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
e580: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
e590: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
e5a0: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
e5b0: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
e5c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
e5d0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
e5e0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
e5f0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
e600: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
e610: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
e620: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
e630: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
e640: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
e650: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
e660: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
e670: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
e680: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
e690: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
e6a0: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
e6b0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
e6c0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31  S:.**.** {H12241
e6d0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
e6e0: 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
e6f0: 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
e700: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
e710: 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
e720: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
e730: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
e740: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
e750: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
e760: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
e770: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
e780: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
e790: 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
e7a0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
e7b0: 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
e7c0: 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
e7d0: 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
e7e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
e7f0: 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
e800: 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
e810: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d  ..**.** {H12243}
e820: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
e830: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
e840: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
e850: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
e860: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
e870: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
e880: 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
e890: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
e8a0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
e8b0: 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
e8c0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
e8d0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
e8e0: 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
e8f0: 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
e900: 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  table..**.** ASS
e910: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
e920: 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {A12252} If a se
e930: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
e940: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
e950: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
e960: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
e970: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
e980: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e990: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
e9a0: 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
e9b0: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
e9c0: 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
e9d0: 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
e9e0: 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
e9f0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
ea00: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
ea10: 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
ea20: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
ea30: 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 0a  dified {H12260}.
ea40: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
ea50: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
ea60: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
ea70: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
ea80: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54  INSERT,.** UPDAT
ea90: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
eaa0: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
eab0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eac0: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
ead0: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
eae0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
eaf0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
eb00: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20  igger contexts. 
eb10: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
eb20: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
eb30: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
eb40: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
eb50: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
eb60: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
eb70: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
eb80: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44  processing, or D
eb90: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
eba0: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
ebb0: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
ebc0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
ebd0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
ebe0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20  akes them is.** 
ebf0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
ec00: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
ec10: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74  ndle is passed t
ec20: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
ec30: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
ec40: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
ec50: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
ec60: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
ec70: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
ec80: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
ec90: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
eca0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
ecb0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
ecc0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
ecd0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
ece0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
ecf0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
ed00: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
ed10: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
ed20: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
ed30: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
ed40: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
ed50: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
ed60: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
ed70: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
ed80: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
ed90: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
eda0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
edb0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
edc0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
edd0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
ede0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
edf0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
ee00: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
ee10: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
ee20: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
ee30: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
ee40: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
ee50: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
ee60: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
ee70: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
ee80: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
ee90: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
eea0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
eeb0: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
eec0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
eed0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
eee0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
eef0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
ef00: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
ef10: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
ef20: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
ef30: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
ef40: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
ef50: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
ef60: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
ef70: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
ef80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ef90: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
efa0: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
efb0: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
efc0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
efd0: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
efe0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  eated..**.** {H1
eff0: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
f000: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
f010: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
f020: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
f030: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
f040: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
f050: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
f060: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
f070: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
f080: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f090: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  )]..**.** ASSUMP
f0a0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
f0b0: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
f0c0: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
f0d0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
f0e0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
f0f0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
f100: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
f110: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
f120: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
f130: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
f140: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
f150: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
f160: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
f170: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
f180: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
f190: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
f1a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f1b0: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
f1c0: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
f1d0: 20 7b 48 31 32 32 37 30 7d 0a 2a 2a 0a 2a 2a 20   {H12270}.**.** 
f1e0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
f1f0: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
f200: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
f210: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
f220: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
f230: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
f240: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
f250: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
f260: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
f270: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
f280: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
f290: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
f2a0: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
f2b0: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
f2c0: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
f2d0: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
f2e0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
f2f0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
f300: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
f310: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
f320: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
f330: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
f340: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
f350: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
f360: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
f370: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
f380: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
f390: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
f3a0: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
f3b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f3c0: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
f3d0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
f3e0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
f3f0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
f400: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
f410: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
f420: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
f430: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
f440: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
f450: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
f460: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
f470: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
f480: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
f490: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
f4a0: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
f4b0: 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
f4c0: 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
f4d0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
f4e0: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
f4f0: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
f500: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
f510: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
f520: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
f530: 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
f540: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f550: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
f560: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
f570: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
f580: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
f590: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
f5a0: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
f5b0: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
f5c0: 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
f5d0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
f5e0: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
f5f0: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
f600: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
f610: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
f620: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
f630: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
f640: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
f650: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
f660: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
f670: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
f680: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
f690: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
f6a0: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
f6b0: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
f6c0: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
f6d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f6e0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
f6f0: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
f700: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
f710: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
f720: 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
f730: 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
f740: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
f750: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
f760: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
f770: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
f780: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
f790: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
f7a0: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
f7b0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
f7c0: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
f7d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f7e0: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
f7f0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f800: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
f810: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f820: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
f830: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
f840: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
f850: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
f860: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
f870: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
f880: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
f890: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
f8a0: 7b 48 31 30 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {H10510}.**.** T
f8b0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
f8c0: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
f8d0: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
f8e0: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
f8f0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
f900: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
f910: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
f920: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
f930: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
f940: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
f950: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
f960: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
f970: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
f980: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
f990: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
f9a0: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
f9b0: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
f9c0: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
f9d0: 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
f9e0: 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
f9f0: 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
fa00: 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
fa10: 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
fa20: 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
fa30: 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
fa40: 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
fa50: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
fa60: 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
fa70: 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
fa80: 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
fa90: 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
faa0: 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
fab0: 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
fac0: 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
fad0: 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
fae0: 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
faf0: 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
fb00: 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
fb10: 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
fb20: 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
fb30: 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
fb40: 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
fb50: 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
fb60: 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
fb70: 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
fb80: 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
fb90: 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
fba0: 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
fbb0: 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
fbc0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
fbd0: 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
fbe0: 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
fbf0: 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
fc00: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
fc10: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
fc20: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
fc30: 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
fc40: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
fc50: 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
fc60: 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
fc70: 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
fc80: 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
fc90: 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
fca0: 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
fcb0: 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
fcc0: 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
fcd0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
fce0: 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
fcf0: 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
fd00: 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
fd10: 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
fd20: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
fd30: 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
fd40: 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
fd50: 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
fd60: 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
fd70: 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
fd80: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
fd90: 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
fda0: 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
fdb0: 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
fdc0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
fdd0: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
fde0: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
fdf0: 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
fe00: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
fe10: 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
fe20: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
fe30: 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
fe40: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
fe50: 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
fe60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
fe70: 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
fe80: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
fe90: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
fea0: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
feb0: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
fec0: 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
fed0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
fee0: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
fef0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
ff00: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
ff10: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
ff20: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
ff30: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
ff40: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
ff50: 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
ff60: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
ff70: 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
ff80: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
ff90: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
ffa0: 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
ffb0: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
ffc0: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
ffd0: 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
ffe0: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
fff0: 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
10000 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
10010 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
10020 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
10030 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
10040 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10050 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
10060 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
10070 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
10080 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
10090 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
100a0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
100b0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
100c0 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
100d0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
100e0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
100f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10100 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
10110 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
10120 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
10130 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
10140 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
10150 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
10160 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
10170 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10180 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
10190 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
101a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
101b0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
101c0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
101d0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
101e0 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
101f0 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
10200 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
10210 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
10220 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
10230 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
10240 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
10250 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
10260 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10270 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10280 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
10290 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
102a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
102b0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
102c0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
102d0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
102e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
102f0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
10300 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
10310 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
10320 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
10330 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
10340 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
10350 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
10360 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
10370 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
10380 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
10390 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
103a0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
103b0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
103c0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
103d0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
103e0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
103f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
10400 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
10410 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
10420 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
10430 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10440 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
10450 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
10460 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
10470 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
10480 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
10490 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
104a0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
104b0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
104c0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
104d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
104e0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
104f0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
10500 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
10510 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
10520 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
10530 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
10540 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
10550 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
10560 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
10570 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
10580 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
10590 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
105a0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
105b0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
105c0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
105d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
105e0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
105f0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
10600 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
10610 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
10620 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
10630 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
10640 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
10650 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
10660 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
10670 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
10680 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
10690 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
106a0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
106b0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
106c0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
106d0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
106e0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
106f0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
10700 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
10710 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
10720 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
10730 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
10740 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
10750 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
10760 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
10770 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
10780 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
10790 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
107a0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
107b0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
107c0 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
107d0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
107e0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
107f0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
10800 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
10810 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
10820 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
10830 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
10840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
10850 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
10860 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
10870 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
10880 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
10890 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
108a0 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
108b0 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
108c0 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
108d0 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
108e0 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
108f0 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
10900 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
10910 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
10920 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
10930 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
10940 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
10950 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
10960 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
10970 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
10980 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
10990 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
109a0 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
109b0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
109c0 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
109d0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
109e0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
109f0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
10a00 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
10a10 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
10a20 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
10a30 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
10a40 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
10a50 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
10a60 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
10a70 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
10a80 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
10a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10aa0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
10ab0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
10ac0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
10ad0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
10ae0 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
10af0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10b00 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
10b10 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
10b20 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
10b30 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
10b40 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10b50 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65  .** {H12311} The
10b60 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10b70 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66  andler(D,C,A)] f
10b80 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10b90 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  place.**        
10ba0 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20    busy callback 
10bb0 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
10bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
10bd0 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ith a new.**    
10be0 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73 79        a new busy
10bf0 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61   handler C and a
10c00 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
10c10 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a  pointer A..**.**
10c20 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20   {H12312} Newly 
10c30 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73  created [databas
10c40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
10c50 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79  hall have a busy
10c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
10c70 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a  dler of NULL..**
10c80 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65  .** {H12314} Whe
10c90 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64  n two or more [d
10ca0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10cb0 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20  ons] share a.** 
10cc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
10cd0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
10ce0 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63  cache | common c
10cf0 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  ache],.**       
10d00 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
10d10 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
10d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
10d30 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
10d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
10d50 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69  cache shall be i
10d60 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
10d70 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73  cache encounters
10d80 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b   a lock..**.** {
10d90 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73  H12316} If a bus
10da0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
10db0 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
10dc0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   then the SQLite
10dd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
10de0 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f 76         that prov
10df0 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67  oked the locking
10e00 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74   event shall ret
10e10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
10e20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38  ]..**.** {H12318
10e30 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69  } SQLite shall i
10e40 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
10e50 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
10e60 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
10e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
10e80 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
10e90 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
10ea0 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
10eb0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
10ec0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
10ed0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
10ee0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
10ef0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
10f00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
10f10 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
10f20 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10f30 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
10f40 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53   event..**.** AS
10f50 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10f60 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79   {A12319} A busy
10f70 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
10f80 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
10f90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
10fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
10fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10fc0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
10fd0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10fe0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
10ff0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
11000 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
11010 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
11020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11030 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
11040 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
11050 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
11060 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
11070 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11080 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
11090 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
110a0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
110b0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
110c0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
110d0 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
110e0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
110f0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
11100 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
11110 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11120 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
11130 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
11140 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65  d. {H12343} Afte
11150 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  r "ms" milliseco
11160 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
11170 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
11180 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
11190 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
111a0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
111b0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
111c0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
111d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
111e0 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
111f0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
11200 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
11210 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
11220 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
11230 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
11240 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
11250 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
11260 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
11270 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
11280 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11290 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
112a0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
112b0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
112c0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
112d0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
112e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
112f0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
11300 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
11310 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
11320 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
11330 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
11340 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
11350 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  NTS:.**.** {H123
11360 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11370 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
11380 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
11390 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 69  override any pri
113a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
113b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
113c0 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eout()] or [sqli
113d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
113e0 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20  ()] setting.**  
113f0 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
11400 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11410 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
11420 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 65   {H12343} If the
11430 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
11440 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
11450 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65  timeout()] is le
11460 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  ss than.**      
11470 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20      or equal to 
11480 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62  zero, then the b
11490 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
114a0 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20  l be cleared so 
114b0 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
114c0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
114d0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
114e0 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
114f0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
11500 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20  .**.** {H12344} 
11510 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
11520 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
11530 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
11540 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
11550 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
11560 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
11570 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62   handler shall b
11580 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61  e set that repea
11590 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20  tedly calls.**  
115a0 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65          the xSle
115b0 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74  ep() method in t
115c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
115d0 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d  | VFS interface]
115e0 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20   until.**       
115f0 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f     either the lo
11600 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74  ck clears or unt
11610 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76  il the cumulativ
11620 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20  e sleep time.** 
11630 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 65           reporte
11640 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70  d back by xSleep
11650 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c  () exceeds N mil
11660 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e  liseconds..*/.in
11670 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
11680 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
11690 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
116a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
116b0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
116c0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
116d0 69 65 73 20 7b 48 31 32 33 37 30 7d 0a 2a 2a 0a  ies {H12370}.**.
116e0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
116f0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
11700 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
11710 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
11720 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
11730 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
11740 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
11750 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
11760 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
11770 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
11780 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
11790 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
117a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
117b0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
117c0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
117d0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
117e0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
117f0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
11800 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
11810 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
11820 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
11830 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
11840 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
11850 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
11860 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
11870 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
11880 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
11890 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
118a0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
118b0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
118c0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
118d0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
118e0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
118f0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
11900 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
11910 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
11920 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
11930 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
11940 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
11950 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
11960 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
11970 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
11980 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
11990 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
119a0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
119b0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
119c0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
119d0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
119e0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
119f0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
11a00 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
11a10 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
11a20 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
11a30 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
11a40 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11a50 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
11a60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
11a70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
11a80 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
11a90 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
11aa0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
11ab0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
11ac0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
11ad0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
11ae0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
11af0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
11b00 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
11b10 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c  .** As an exampl
11b20 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
11b30 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
11b40 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
11b50 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
11b60 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
11b70 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11b80 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
11b90 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
11ba0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
11bb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
11bc0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
11bd0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
11be0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
11bf0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
11c00 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
11c10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
11c20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
11c30 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
11c40 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
11c50 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
11c60 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
11c70 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
11c80 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
11c90 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11ca0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
11cb0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
11cc0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
11cd0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
11ce0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
11cf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11d00 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
11d10 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
11d20 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
11d30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11d40 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
11d50 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11d60 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
11d70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11d80 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
11d90 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11da0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
11db0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
11dc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
11dd0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
11de0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
11df0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
11e00 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11e10 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
11e20 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
11e30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
11e40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11e50 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
11e60 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
11e70 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
11e80 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
11e90 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
11ea0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11eb0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
11ec0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
11ed0 65 74 65 72 2e 20 20 49 74 20 72 65 74 75 72 6e  eter.  It return
11ee0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
11ef0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
11f00 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
11f10 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
11f20 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 63  *.** After the c
11f30 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
11f40 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
11f50 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c 20 69  ng the result, i
11f60 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73  t should.** pass
11f70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
11f80 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
11fa0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
11fb0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
11fc0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
11fd0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
11fe0 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
11ff0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
12000 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
12010 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
12020 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
12030 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
12040 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
12050 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
12060 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
12070 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
12080 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
12090 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
120a0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
120b0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
120c0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
120d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
120e0 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
120f0 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
12100 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
12110 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
12120 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
12130 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12140 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
12150 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
12160 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
12170 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
12180 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
12190 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
121a0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
121b0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
121c0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
121d0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
121e0 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
121f0 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
12200 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
12210 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
12220 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
12230 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
12240 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
12250 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
12260 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
12270 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
12280 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
12290 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
122a0 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71 6c 69  2371} If a [sqli
122b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
122c0 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20   fails a memory 
122d0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
122e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 20  .**          it 
122f0 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65 20 72  shall free the r
12300 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64 65  esult table unde
12310 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20  r construction, 
12320 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20 20 20  abort the.**    
12330 20 20 20 20 20 20 71 75 65 72 79 20 69 6e 20 70        query in p
12340 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61 6e 79  rocess, skip any
12350 20 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72   subsequent quer
12360 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20  ies, set the.** 
12370 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52 65 73           *pazRes
12380 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69 6e 74  ult output point
12390 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72  er to NULL and r
123a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
123b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  MEM]..**.** {H12
123c0 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e 43 6f  373} If the pnCo
123d0 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74  lumn parameter t
123e0 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
123f0 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
12400 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
12410 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
12420 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
12430 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
12440 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
12450 20 20 20 20 20 20 20 20 77 72 69 74 65 20 74 68          write th
12460 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
12470 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  mns in the.**   
12480 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
12490 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
124a0 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a  nto *pnColumn..*
124b0 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20 49 66  *.** {H12374} If
124c0 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72 61 6d   the pnRow param
124d0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
124e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
124f0 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
12500 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75 63        then a suc
12510 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
12520 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
12530 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c  et_table()] shal
12540 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72  l.**          wr
12550 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20  ites the number 
12560 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a  of rows in the.*
12570 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
12580 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
12590 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a  ry into *pnRow..
125a0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41  **.** {H12376} A
125b0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
125c0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
125d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
125e0 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a  that computes.**
125f0 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f 77 73            N rows
12600 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74 68 20   of result with 
12610 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f  C columns per ro
12620 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61  w shall make *pa
12630 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20  zResult.**      
12640 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20      point to an 
12650 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
12660 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72  s to (N+1)*C str
12670 69 6e 67 73 20 77 68 65 72 65 20 74 68 65 20 66  ings where the f
12680 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
12690 20 43 20 73 74 72 69 6e 67 73 20 61 72 65 20 63   C strings are c
126a0 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f  olumn names as o
126b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
126c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
126d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
126e0 20 61 6e 64 20 74 68 65 20 72 65 73 74 20 61 72   and the rest ar
126f0 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20  e column result 
12700 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
12710 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d     obtained from
12720 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
12730 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
12740 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76 61 6c  {H12379} The val
12750 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a 52 65  ues in the pazRe
12760 73 75 6c 74 20 61 72 72 61 79 20 72 65 74 75 72  sult array retur
12770 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
12780 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20  get_table()].** 
12790 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72           shall r
127a0 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e 74 69  emain valid unti
127b0 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b 73 71  l cleared by [sq
127c0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
127d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ()]..**.** {H123
127e0 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  82} When an erro
127f0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
12800 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73  evaluation of [s
12810 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12820 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
12830 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  the function sha
12840 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73 75 6c  ll set *pazResul
12850 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65  t to NULL, write
12860 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
12870 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
12880 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
12890 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
128a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65  _malloc()], make
128b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 2a 70  .**          **p
128c0 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f  zErrmsg point to
128d0 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65 73 73   that error mess
128e0 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  age, and return 
128f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 70  a.**          ap
12900 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
12910 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
12920 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12930 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
12940 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
12950 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
12960 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
12970 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
12980 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
12990 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
129a0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
129b0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
129c0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
129d0 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
129e0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
129f0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
12a00 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
12a10 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
12a20 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
12a30 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
12a40 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
12a50 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
12a60 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
12a70 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
12a80 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
12a90 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
12aa0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
12ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
12ac0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
12ad0 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
12ae0 7b 48 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {H17400}.**.** T
12af0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
12b00 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20  e workalikes of 
12b10 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
12b20 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
12b30 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
12b40 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12b50 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
12b60 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
12b70 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
12b80 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
12b90 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
12ba0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
12bb0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
12bc0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12bd0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
12be0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
12bf0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
12c00 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
12c10 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
12c20 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f  te3_free()].  Bo
12c30 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
12c40 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
12c50 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
12c60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
12c70 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
12c80 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
12c90 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
12ca0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
12cb0 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33  **.** In sqlite3
12cc0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
12cd0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
12ce0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
12cf0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
12d00 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
12d10 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
12d20 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
12d30 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
12d40 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
12d50 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
12d60 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
12d70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
12d80 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
12d90 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
12da0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
12db0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
12dc0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
12dd0 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69  rintf().  This i
12de0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
12df0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
12e00 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
12e10 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
12e20 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
12e30 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e  ompatibility.  N
12e40 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
12e50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12e60 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
12e70 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
12e80 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
12e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
12ea0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
12eb0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
12ec0 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65   the buffer.  We
12ed0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
12ee0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
12ef0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
12f00 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
12f10 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
12f20 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
12f30 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
12f40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
12f50 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
12f60 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
12f70 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
12f80 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
12f90 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  * As long as the
12fa0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
12fb0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
12fc0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
12fd0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
12fe0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
12ff0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
13000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
13010 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
13020 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
13030 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
13040 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
13050 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
13060 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
13070 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
13080 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
13090 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
130a0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
130b0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
130c0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
130d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
130e0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
130f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
13100 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
13110 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
13120 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
13130 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
13140 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
13150 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
13160 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
13170 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
13180 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
13190 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
131a0 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
131b0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
131c0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
131d0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
131e0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
131f0 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
13200 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
13210 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
13220 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
13230 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
13240 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
13250 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
13260 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
13270 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
13280 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
13290 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
132a0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
132b0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
132c0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
132d0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
132e0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
132f0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
13300 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
13310 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
13320 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
13330 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
13340 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13350 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
13360 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
13370 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
13380 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13390 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
133a0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
133b0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
133c0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
133d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
133e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
133f0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
13400 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
13410 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
13420 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
13430 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13440 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
13450 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
13460 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
13470 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13480 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
13490 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
134a0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
134b0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
134c0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
134d0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
134e0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
134f0 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
13500 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13510 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
13520 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
13530 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
13540 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
13550 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13560 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
13570 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
13580 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
13590 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
135a0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
135b0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
135c0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
135d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
135e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
135f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
13600 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
13610 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
13620 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
13630 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
13640 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
13650 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
13660 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
13670 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
13680 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
13690 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
136a0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
136b0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
136c0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
136d0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
136e0 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
136f0 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
13700 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
13710 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
13720 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
13730 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
13740 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
13750 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
13760 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
13770 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
13780 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
13790 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
137a0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
137b0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e  ingle quotes) in
137c0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51   place of the %Q
137d0 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f   option.  So, fo
137e0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
137f0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
13800 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13810 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
13820 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
13830 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
13840 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
13850 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13860 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13870 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13880 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13890 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
138a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
138b0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
138c0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
138d0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
138e0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
138f0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
13900 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
13910 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
13920 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
13930 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72  .** The "%z" for
13940 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
13950 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b  orks exactly lik
13960 65 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a  e "%s" with the.
13970 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
13980 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
13990 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
139a0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
139b0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
139c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
139d0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
139e0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b   input string. {
139f0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  END}.**.** INVAR
13a00 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
13a10 37 34 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7403}  The [sqli
13a20 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61  te3_mprintf()] a
13a30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72  nd [sqlite3_vmpr
13a40 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
13a50 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  es.**           
13a60 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f  return either po
13a70 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
13a80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
13a90 73 74 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a  strings held in.
13aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d  **           mem
13ab0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
13ac0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13ad0 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69  c()] or NULL poi
13ae0 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20  nters if.**     
13af0 20 20 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20        a call to 
13b00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13b10 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  )] fails..**.** 
13b20 7b 48 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73  {H17406}  The [s
13b30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13b40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69  )] interface wri
13b50 74 65 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  tes a zero-termi
13b60 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
13b70 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
13b80 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 20  into the buffer 
13b90 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
13ba0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
13bb0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
13bc0 70 72 6f 76 69 64 65 64 20 74 68 61 74 20 74 68  provided that th
13bd0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13be0 72 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  r is greater tha
13bf0 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48  n zero..**.** {H
13c00 31 37 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c  17407}  The [sql
13c10 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
13c20 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
13c30 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20  not write slots 
13c40 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
13c50 69 74 73 20 6f 75 74 70 75 74 20 62 75 66 66 65  its output buffe
13c60 72 20 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61  r (the second pa
13c70 72 61 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65  rameter) outside
13c80 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20   the range.**   
13c90 20 20 20 20 20 20 20 20 6f 66 20 30 20 74 68 72          of 0 thr
13ca0 6f 75 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20  ough N-1 (where 
13cb0 4e 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  N is the first p
13cc0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20  arameter).**    
13cd0 20 20 20 20 20 20 20 72 65 67 61 72 64 6c 65 73         regardles
13ce0 73 20 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20  s of the length 
13cf0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a  of the string.**
13d00 20 20 20 20 20 20 20 20 20 20 20 72 65 71 75 65             reque
13d10 73 74 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d  sted by the form
13d20 61 74 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  at specification
13d30 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..*/.char *sqlit
13d40 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
13d50 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
13d60 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
13d70 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
13d80 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
13d90 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
13da0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
13db0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
13dc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13dd0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
13de0 6e 20 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37  n Subsystem {H17
13df0 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  300}.**.** The S
13e00 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
13e10 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
13e20 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
13e30 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
13e40 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
13e50 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
13e60 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
13e70 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
13e80 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13e90 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
13ea0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
13eb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13ec0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
13ed0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
13ee0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
13ef0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
13f00 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  rations..**.** T
13f10 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
13f20 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
13f30 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13f40 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
13f50 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
13f60 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
13f70 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
13f80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49   parameter..** I
13f90 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
13fa0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
13fb0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
13fc0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
13fd0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
13fe0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
13ff0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
14000 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
14010 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
14020 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
14030 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14040 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
14050 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
14060 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  ** Calling sqlit
14070 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
14080 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
14090 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
140a0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
140b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
140c0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
140d0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
140e0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
140f0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68  t be reused.  Th
14100 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
14110 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
14120 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
14130 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
14140 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
14150 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
14160 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
14170 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
14180 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
14190 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
141a0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
141b0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
141c0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
141d0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
141e0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
141f0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
14200 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
14210 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
14220 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
14230 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
14240 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
14250 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
14260 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
14270 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
14280 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
14290 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
142a0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
142b0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
142c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
142d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
142e0 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  r sqlite3_free()
142f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
14300 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
14310 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
14320 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
14330 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
14340 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
14350 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
14360 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
14370 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
14380 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
14390 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
143a0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
143b0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
143c0 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
143d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
143e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
143f0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
14400 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
14410 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
14420 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
14430 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
14440 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
14450 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14460 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14470 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
14480 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14490 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
144a0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
144b0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
144c0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
144d0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
144e0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
144f0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
14500 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
14510 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14520 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14530 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
14540 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14550 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
14560 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
14570 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
14580 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
14590 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
145a0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
145b0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
145c0 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
145d0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
145e0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
145f0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
14600 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
14610 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
14620 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
14630 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
14640 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
14650 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
14660 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
14670 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
14680 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
14690 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
146a0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
146b0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
146c0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
146d0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
146e0 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
146f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
14700 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
14710 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14720 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
14730 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
14740 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
14750 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
14760 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
14770 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
14780 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14790 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
147a0 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
147b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
147c0 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
147d0 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
147e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
147f0 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
14800 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
14810 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
14820 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
14830 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
14840 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
14850 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
14860 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
14870 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
14880 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
14890 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
148a0 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
148b0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
148c0 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
148d0 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
148e0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
148f0 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
14900 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
14910 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
14920 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
14930 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
14940 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
14950 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
14960 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
14970 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
14980 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
14990 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
149a0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
149b0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
149c0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
149d0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
149e0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
149f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
14a00 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14a10 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
14a20 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
14a30 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
14a40 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
14a50 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
14a60 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
14a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
14a80 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
14a90 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
14aa0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
14ab0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
14ac0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
14ad0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
14ae0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
14af0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
14b00 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
14b10 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
14b20 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
14b30 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
14b40 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
14b50 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
14b60 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
14b70 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
14b80 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
14b90 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
14ba0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
14bb0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
14bc0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
14bd0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
14be0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
14bf0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
14c00 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d  :.**.** {H17303}
14c10 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
14c20 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
14c30 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
14c40 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  er a pointer to.
14c50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e  **           a n
14c60 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
14c70 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
14c80 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
14c90 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
14ca0 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
14cb0 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20   aligned, or it 
14cc0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
14cd0 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  it is unable.** 
14ce0 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c            to ful
14cf0 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
14d00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d  ..**.** {H17304}
14d10 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
14d20 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
14d30 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
14d40 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
14d50 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
14d60 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
14d70 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
14d80 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20  * {H17305}  The 
14d90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
14da0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
14db0 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
14dc0 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
14dd0 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
14de0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14df0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
14e00 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
14e10 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
14e20 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
14e30 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
14e40 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  H17306}  A call 
14e50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
14e60 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
14e70 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
14e80 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63  ** {H17310}  A c
14e90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
14ea0 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
14eb0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
14ec0 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
14ed0 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
14ee0 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
14ef0 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {H17312}  A cal
14f00 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
14f10 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
14f20 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
14f30 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
14f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
14f50 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(P)]..**.** {H1
14f60 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
14f70 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
14f80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
14f90 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14fa0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
14fb0 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
14fc0 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
14fd0 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
14fe0 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
14ff0 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
15000 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
15010 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65  ** {H17318}  The
15020 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15030 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
15040 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
15050 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
15060 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
15070 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
15080 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
15090 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
150a0 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
150b0 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
150c0 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
150d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
150e0 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65  ** {H17321}  Whe
150f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
15100 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
15110 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
15120 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
15130 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
15140 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
15150 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
15160 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
15170 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ewly.**         
15180 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63    allocated bloc
15190 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68  k, where K is th
151a0 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e  e lesser of N an
151b0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  d the size of.**
151c0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62             the b
151d0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
151e0 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  H17322}  When [s
151f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
15200 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
15210 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
15220 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
15230 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
15240 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
15250 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68  .** {H17323}  Wh
15260 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
15270 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
15280 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
15290 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
152a0 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
152b0 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
152c0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
152d0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d  :.**.** {A17350}
152e0 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
152f0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
15300 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
15310 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15320 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
15330 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
15340 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
15350 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
15360 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
15370 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
15380 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
15390 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
153a0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
153b0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20   that have.**   
153c0 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20          not yet 
153d0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
153e0 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54  *.** {A17351}  T
153f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
15400 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
15410 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
15420 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
15430 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
15440 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
15450 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
15460 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  g.**           [
15470 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
15480 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
15490 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
154a0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
154b0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
154c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
154d0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
154e0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
154f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15500 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
15510 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
15520 7b 48 31 37 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53  {H17370}.**.** S
15530 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
15540 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
15550 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
15560 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
15570 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
15580 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
15590 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
155a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
155b0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
155c0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
155d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
155e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
155f0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
15600 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
15610 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
15620 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
15630 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
15640 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
15650 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
15660 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
15670 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
15680 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
15690 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
156a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
156b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
156c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
156d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
156e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
156f0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
15700 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
15710 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
15720 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
15730 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
15740 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
15750 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
15760 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
15770 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
15780 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
15790 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
157a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
157b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
157c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
157d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
157e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
157f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
15800 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
15810 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
15820 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
15830 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
15840 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
15850 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
15860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
15870 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
15880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
15890 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
158a0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
158b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
158c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
158d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
158e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
158f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
15900 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
15910 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
15920 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
15930 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
15940 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15950 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
15960 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
15970 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
15980 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
15990 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
159a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
159b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
159c0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
159d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
159e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
159f0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
15a00 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
15a10 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15a20 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
15a30 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
15a40 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
15a50 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
15a60 74 6f 72 20 7b 48 31 37 33 39 30 7d 0a 2a 2a 0a  tor {H17390}.**.
15a70 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
15a80 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
15a90 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
15aa0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
15ab0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
15ac0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
15ad0 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
15ae0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
15af0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
15b00 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
15b10 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
15b20 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
15b30 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
15b40 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
15b50 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
15b60 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
15b70 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
15b80 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
15b90 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
15ba0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
15bb0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
15bc0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
15bd0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
15be0 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
15bf0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
15c00 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
15c10 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
15c20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
15c30 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
15c40 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
15c50 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
15c60 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
15c70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
15c80 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
15c90 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
15ca0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
15cb0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
15cc0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
15cd0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
15ce0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
15cf0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
15d00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
15d10 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
15d20 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
15d30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
15d40 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
15d50 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
15d60 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
15d70 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
15d80 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15d90 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d  :.**.** {H17392}
15da0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61   The [sqlite3_ra
15db0 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69  ndomness(N,P)] i
15dc0 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
15dd0 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20  N bytes of.**   
15de0 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c         high-qual
15df0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
15e00 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
15e10 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  r P..*/.void sql
15e20 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
15e30 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
15e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15e50 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
15e60 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
15e70 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 0a  lbacks {H12500}.
15e80 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
15e90 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
15ea0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
15eb0 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
15ec0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
15ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
15ee0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
15ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
15f00 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15f10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15f20 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
15f30 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
15f40 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
15f50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15f60 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
15f70 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
15f80 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
15f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
15fa0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
15fb0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
15fc0 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
15fd0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
15fe0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
15ff0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
16000 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
16010 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
16020 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
16030 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
16040 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16050 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
16060 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
16070 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
16080 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16090 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
160a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
160b0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
160c0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
160d0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
160e0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
160f0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
16100 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
16110 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
16120 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
16130 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
16140 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
16150 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
16160 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
16170 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
16180 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
16190 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
161a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
161b0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
161c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
161d0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
161e0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
161f0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
16200 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16210 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
16220 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
16230 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
16240 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
16250 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
16260 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
16270 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
16280 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
16290 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
162a0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
162b0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
162c0 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
162d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
162e0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
162f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16300 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
16310 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
16320 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
16330 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
16340 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
16350 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
16360 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
16370 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
16380 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
16390 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
163a0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
163b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
163c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
163d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
163e0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
163f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
16400 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
16410 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
16420 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
16430 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
16440 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
16450 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
16460 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
16470 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
16480 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
16490 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
164a0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
164b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
164c0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
164d0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
164e0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
164f0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
16500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
16510 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
16520 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16530 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
16540 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
16550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16560 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
16570 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
16580 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
16590 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
165a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
165b0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
165c0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
165d0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
165e0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
165f0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
16600 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
16610 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
16620 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
16630 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
16640 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
16650 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
16660 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
16670 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
16680 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
16690 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
166a0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
166b0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
166c0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
166d0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
166e0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
166f0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
16700 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
16710 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
16720 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
16730 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
16740 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
16750 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
16760 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
16770 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
16780 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
16790 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
167a0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
167b0 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
167c0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
167d0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
167e0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
167f0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
16800 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
16810 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
16820 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
16830 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
16840 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
16850 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
16860 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
16870 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
16880 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
16890 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
168a0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
168b0 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
168c0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
168d0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
168e0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
168f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16900 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
16910 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
16920 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
16930 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
16940 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
16950 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
16960 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
16970 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
16980 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
16990 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
169a0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
169b0 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
169c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
169d0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
169e0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
169f0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
16a00 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
16a10 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
16a20 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
16a30 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
16a40 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
16a50 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
16a60 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
16a70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a80 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
16a90 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
16aa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16ab0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
16ac0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
16ad0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
16ae0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
16af0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
16b00 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
16b10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
16b20 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
16b30 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ault..**.** Note
16b40 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
16b50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
16b60 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
16b70 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
16b80 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
16b90 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
16ba0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
16bb0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
16bc0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
16bd0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
16be0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
16bf0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
16c00 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31  S:.**.** {H12501
16c10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
16c20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
16c30 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
16c40 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
16c50 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
16c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
16c70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16c80 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
16c90 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
16ca0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16cb0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
16cc0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
16cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
16ce0 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  g compiled..**.*
16cf0 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68  * {H12503} If th
16d00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16d10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
16d20 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
16d30 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
16d40 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
16d50 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
16d60 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
16d70 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
16d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
16d90 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16da0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16db0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
16dc0 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
16dd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
16de0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
16df0 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
16e00 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
16e10 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
16e20 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
16e30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
16e40 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57  **.** {H12504} W
16e50 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
16e60 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
16e70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
16e80 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
16e90 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
16ea0 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65  ibed is processe
16eb0 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a  d normally..**.*
16ec0 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20  * {H12505} When 
16ed0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16ee0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16ef0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
16f00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
16f10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16f20 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16f30 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
16f40 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  used the.**     
16f50 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
16f60 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
16f70 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20  shall fail.**   
16f80 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b         with an [
16f90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
16fa0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
16fb0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
16fc0 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 69            explai
16fd0 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 73  ning that access
16fe0 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a   is denied..**.*
16ff0 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68  * {H12506} If th
17000 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
17010 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
17020 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17030 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
17040 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
17050 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e  [SQLITE_READ] an
17060 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
17070 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17080 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
17090 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74  QLITE_IGNORE], t
170a0 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
170b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
170c0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
170d0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
170e0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
170f0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
17100 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
17110 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
17120 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
17130 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
17140 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
17150 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d  ..**.** {H12507}
17160 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
17170 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
17180 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17190 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
171a0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
171b0 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
171c0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
171d0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
171e0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
171f0 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
17200 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
17210 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
17220 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a  LITE_DENY]..**.*
17230 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66  * {H12510} The f
17240 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17250 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17270 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
17280 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 72     the third par
17290 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
172a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
172b0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
172c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  ce..**.** {H1251
172d0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
172e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
172f0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
17300 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
17310 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
17320 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
17330 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17340 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
17350 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
17360 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
17370 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20  .**.** {H12512} 
17380 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
17390 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
173a0 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
173b0 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ck are.**       
173c0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
173d0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
173e0 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20  contain.**      
173f0 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64      additional d
17400 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
17410 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
17420 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17430 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 61  {H12520} Each ca
17440 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
17450 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
17460 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20   overrides.**   
17470 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69         any previ
17480 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20  ously installed 
17490 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
174a0 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c  * {H12521} A NUL
174b0 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
174c0 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
174d0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  rization.**     
174e0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73       callback is
174f0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
17500 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 66  {H12522} The def
17510 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
17520 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  is NULL..*/.int 
17530 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17540 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
17550 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
17560 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
17570 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
17580 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17590 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
175a0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
175b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
175c0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
175d0 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31  Return Codes {H1
175e0 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2590}.**.** The 
175f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17600 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17610 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
17620 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
17630 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
17640 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
17650 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
17660 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
17670 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
17680 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
17690 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
176a0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
176b0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
176c0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
176d0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
176e0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
176f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
17700 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
17710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
17720 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
17730 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
17740 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
17750 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
17760 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
17770 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
17780 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
17790 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
177a0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
177b0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
177c0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
177d0 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12550}.**.** The
177e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
177f0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
17800 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
17810 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
17820 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
17830 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
17840 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
17850 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
17860 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
17870 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
17880 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
17890 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
178a0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
178b0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
178c0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
178d0 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
178e0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
178f0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
17900 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17910 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
17920 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
17930 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
17940 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
17950 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
17960 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
17970 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
17980 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
17990 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
179a0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
179b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
179c0 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
179d0 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
179e0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
179f0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
17a00 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
17a10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17a20 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
17a30 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
17a40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17a50 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
17a60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
17a70 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
17a80 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
17a90 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
17aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17ab0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17ac0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
17ad0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
17ae0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
17af0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
17b00 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
17b10 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
17b20 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
17b30 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
17b40 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
17b50 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
17b60 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
17b70 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
17b80 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65  .** {H12551} The
17b90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17ba0 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20  r to an.**      
17bb0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17bc0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17bd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17be0 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20  k] is always an 
17bf0 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
17c00 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
17c10 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
17c20 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
17c30 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a  es what action.*
17c40 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65  *          is be
17c50 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a  ing authorized..
17c60 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54  **.** {H12552} T
17c70 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
17c80 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
17c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17ca0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17cb0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61  izer | authoriza
17cc0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a  tion callback].*
17cd0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
17ce0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
17cf0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
17d00 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  on which.**     
17d10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
17d20 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
17d30 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
17d40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17d50 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
17d60 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
17d70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
17d80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
17d90 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17da0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
17db0 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
17dc0 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
17dd0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
17de0 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
17df0 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
17e00 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
17e10 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54  **.** {H12554} T
17e20 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
17e30 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
17e40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17e50 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17e60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17e70 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
17e80 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
17e90 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
17ea0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
17eb0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
17ec0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
17ed0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
17ee0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
17ef0 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
17f00 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
17f10 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
17f20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
17f30 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
17f40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17f50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17f60 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
17f70 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
17f80 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
17f90 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
17fa0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
17fb0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17fc0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17fd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17fe0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
17ff0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
18000 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18010 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18020 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18030 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
18040 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
18050 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18060 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18070 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18080 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
18090 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
180a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
180b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
180c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
180d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
180e0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
180f0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18100 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18120 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
18130 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
18140 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18150 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18170 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
18180 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
18190 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
181a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
181b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
181c0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
181d0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
181e0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
181f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
18210 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
18220 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
18230 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18240 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18250 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18260 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
18270 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
18280 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18290 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
182a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
182b0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
182c0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
182d0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
182e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
182f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18300 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
18310 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
18320 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18330 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18340 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
18350 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
18360 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18370 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18380 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18390 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
183a0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
183b0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
183c0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
183d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
183e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
183f0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
18400 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18410 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18420 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18430 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
18440 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
18450 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18460 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18470 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18480 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
18490 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
184a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
184b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
184c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
184d0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
184e0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
184f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18500 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18520 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
18530 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
18540 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
18550 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
18560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18570 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
18580 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
18590 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
185a0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
185b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
185c0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
185d0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
185e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
185f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18610 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
18620 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
18630 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
18640 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
18660 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
18670 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
18680 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
18690 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
186a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
186b0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
186c0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
186d0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
186e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
186f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
18700 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
18710 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
18720 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
18730 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18740 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
18750 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
18760 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
18770 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
18780 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18790 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
187a0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
187b0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
187c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
187d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
187e0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
187f0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
18800 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
18810 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18830 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18840 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
18850 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18860 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
18870 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18880 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
18890 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
188a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
188b0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
188c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
188d0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
188e0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
188f0 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
18900 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
18910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18920 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
18930 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
18940 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
18950 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
18960 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
18970 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
18980 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 0a 2a  tions {H12280}.*
18990 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
189a0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
189b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
189c0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
189d0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
189e0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
189f0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
18a00 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18a10 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
18a20 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
18a30 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
18a40 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
18a50 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
18a60 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
18a70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
18a80 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
18a90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18aa0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
18ab0 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
18ac0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
18ad0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
18ae0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
18af0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
18b00 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
18b10 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
18b20 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
18b30 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
18b40 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
18b50 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
18b60 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
18b70 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
18b80 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
18b90 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
18ba0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
18bb0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
18bc0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18bd0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
18be0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
18bf0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
18c00 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
18c10 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
18c20 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18c30 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
18c40 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
18c50 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
18c60 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
18c70 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
18c80 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
18c90 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
18ca0 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   run..**.** The 
18cb0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
18cc0 29 20 41 50 49 20 69 73 20 63 75 72 72 65 6e 74  ) API is current
18cd0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  ly considered ex
18ce0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a  perimental and.*
18cf0 2a 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20  * is subject to 
18d00 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61  change or remova
18d10 6c 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  l in a future re
18d20 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lease..**.** The
18d30 20 74 72 69 67 67 65 72 20 72 65 70 6f 72 74 69   trigger reporti
18d40 6e 67 20 66 65 61 74 75 72 65 20 6f 66 20 74 68  ng feature of th
18d50 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18d60 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a   is considered.*
18d70 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  * experimental a
18d80 6e 64 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f  nd is subject to
18d90 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d 6f 76   change or remov
18da0 61 6c 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  al in future rel
18db0 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74 75 72 65  eases..** Future
18dc0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
18dd0 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
18de0 64 64 20 6e 65 77 20 74 72 61 63 65 20 63 61 6c  dd new trace cal
18df0 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74  lback.** invocat
18e00 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ions..**.** INVA
18e10 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
18e20 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
18e30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
18e40 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
18e50 74 65 33 5f 74 72 61 63 65 28 29 5d 20 69 73 0a  te3_trace()] is.
18e60 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
18e70 65 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74  ever an SQL stat
18e80 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
18e90 6e 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e  ns to execute an
18ea0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  d.**          wh
18eb0 65 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72  enever a trigger
18ec0 20 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73   subprogram firs
18ed0 74 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e  t begins to run.
18ee0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20  .**.** {H12282} 
18ef0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
18f00 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 6f  lite3_trace()] o
18f10 76 65 72 72 69 64 65 73 20 74 68 65 20 70 72 65  verrides the pre
18f20 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
18f30 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
18f40 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
18f50 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20  *.** {H12283} A 
18f60 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
18f70 61 63 6b 20 64 69 73 61 62 6c 65 73 20 74 72 61  ack disables tra
18f80 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  cing..**.** {H12
18f90 32 38 34 7d 20 54 68 65 20 66 69 72 73 74 20 61  284} The first a
18fa0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74  rgument to the t
18fb0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
18fc0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
18fd0 20 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74         the point
18fe0 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
18ff0 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
19000 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
19010 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
19020 35 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  5} The second ar
19030 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
19040 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
19050 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
19060 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
19070 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  F-8 string conta
19080 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  ining the origin
19090 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  al text.**      
190a0 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73      of the SQL s
190b0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
190c0 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b  as passed into [
190d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
190e0 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
190f0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
19100 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63  ent, or an SQL c
19110 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e  omment indicatin
19120 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a  g the beginning.
19130 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
19140 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
19150 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ram..**.** {H122
19160 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  87} The callback
19170 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
19180 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
19190 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69  _profile()] is i
191a0 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20  nvoked.**       
191b0 20 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73     as each SQL s
191c0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
191d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38  s..**.** {H12288
191e0 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
191f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
19200 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
19210 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20   a copy of.**   
19220 20 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70         the 3rd p
19230 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
19240 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e  ite3_profile()].
19250 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20  .**.** {H12289} 
19260 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19270 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
19280 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
19290 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  a.**          ze
192a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
192b0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20  F-8 string that 
192c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d  contains the com
192d0 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a  plete text of.**
192e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51            the SQ
192f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
19300 74 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20  t was processed 
19310 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
19320 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
19330 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
19340 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b  ivalent..**.** {
19350 48 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72  H12290} The thir
19360 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19370 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19380 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61  ack is an estima
19390 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  te.**          o
193a0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
193b0 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77  nanoseconds of w
193c0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72  all-clock time r
193d0 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20  equired to.**   
193e0 20 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53         run the S
193f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f  QL statement fro
19400 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73  m start to finis
19410 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  h..*/.void *sqli
19420 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
19430 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
19440 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
19450 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  ar*), void*);.vo
19460 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
19470 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
19480 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
19490 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
194a0 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
194b0 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
194c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
194d0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
194e0 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 0a 2a  backs {H12910}.*
194f0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
19500 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
19510 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19520 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
19530 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
19540 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
19550 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
19560 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
19570 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
19580 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
19590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
195a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
195b0 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
195c0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
195d0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
195e0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
195f0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
19600 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
19610 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
19620 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19630 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
19640 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
19650 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
19660 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
19670 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
19680 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
19690 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
196a0 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62  n a GUI dialog b
196b0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ox..**.** INVARI
196c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
196d0 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  911} The callbac
196e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
196f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19700 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19710 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
19720 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
19730 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
19740 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
19750 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
19760 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19770 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32  ]..**.** {H12912
19780 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
19790 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
197a0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72  ed once for ever
197b0 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20  y N virtual.**  
197c0 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20          machine 
197d0 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e  opcodes, where N
197e0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
197f0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
19800 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
19810 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19820 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
19830 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
19840 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
19850 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20  lback.  If N is 
19860 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c  less than 1, sql
19870 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
19880 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
19890 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61      acts as if a
198a0 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68   NULL progress h
198b0 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20  andler had been 
198c0 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a  specified..**.**
198d0 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72   {H12913} The pr
198e0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
198f0 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69  itself is identi
19900 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72  fied by the thir
19910 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  d.**          ar
19920 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19930 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
19940 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er()..**.** {H12
19950 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20  914} The fourth 
19960 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19970 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19980 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20  dler() is a.**  
19990 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
199a0 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
199b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
199c0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
199d0 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
199e0 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
199f0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35  d..**.** {H12915
19a00 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
19a10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19a20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
19a30 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a   than N opcodes.
19a40 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
19a50 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e  g executed, then
19a60 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19a70 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
19a80 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
19a90 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61  H12916} Every ca
19aa0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
19ab0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
19ac0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
19ad0 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72  verwrites any pr
19ae0 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
19af0 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e  red progress han
19b00 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  dler..**.** {H12
19b10 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67  917} If the prog
19b20 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
19b30 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68  lback is NULL th
19b40 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a  en no progress.*
19b50 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c  *          handl
19b60 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  er is invoked..*
19b70 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66  *.** {H12918} If
19b80 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
19ba0 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
19bb0 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  an 0, then.**   
19bc0 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76         the behav
19bd0 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c  ior is a if [sql
19be0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19bf0 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65  ] had been calle
19c00 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
19c10 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
19c20 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
19c30 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
19c40 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
19c50 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
19c60 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
19c70 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31  e Connection {H1
19c80 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  2700}.**.** Thes
19c90 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
19ca0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
19cb0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
19cc0 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
19cd0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
19ce0 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c  rgument. The fil
19cf0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
19d00 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
19d10 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
19d20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
19d30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19d40 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
19d50 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
19d60 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
19d70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
19d80 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63  ). A [database c
19d90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
19da0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
19db0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
19dc0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
19dd0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
19de0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
19df0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
19e00 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
19e10 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
19e20 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
19e30 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
19e40 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
19e50 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
19e60 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
19e70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
19e80 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
19e90 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74  ject. If the dat
19ea0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19eb0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
19ec0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
19ed0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
19ee0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
19ef0 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
19f00 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
19f10 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  turned.  The.** 
19f20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
19f30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
19f40 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
19f50 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
19f60 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
19f70 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
19f80 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
19f90 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
19fa0 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
19fb0 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
19fc0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
19fd0 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
19fe0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
19ff0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1a000 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1a010 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1a020 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1a030 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1a040 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1a050 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1a060 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1a070 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1a080 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1a090 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1a0a0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1a0b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1a0c0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1a0d0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1a0e0 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1a0f0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1a100 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1a110 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1a120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1a130 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1a140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1a150 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1a160 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1a170 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1a180 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1a190 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1a1a0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1a1b0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1a1c0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
1a1d0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1a1e0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1a1f0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1a200 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1a210 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1a220 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1a230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a240 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a  UTEX] flag:.**.*
1a250 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1a260 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1a270 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1a280 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a290 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1a2a0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1a2b0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a2c0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1a2d0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a2e0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a2f0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1a300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a310 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1a320 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1a330 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1a340 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1a350 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1a360 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1a370 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1a380 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1a390 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1a3a0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1a3b0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1a3c0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1a3d0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1a3e0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1a3f0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1a400 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1a410 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a420 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1a430 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1a440 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1a450 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1a460 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1a470 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1a480 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1a490 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1a4a0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1a4b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1a4c0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1a4d0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1a4e0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a4f0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1a500 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1a510 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1a520 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1a530 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1a540 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1a550 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1a560 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1a570 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1a580 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1a590 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1a5a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1a5b0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c  N_NOMUTEX] flag,
1a5c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1a5d0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1a5e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  .**.** If the [S
1a5f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a600 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1a610 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e   then mutexes on
1a620 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b   the.** opened [
1a630 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a640 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65  ion] are disable
1a650 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61  d and the applia
1a660 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73  tion must.** ins
1a670 75 72 65 20 74 68 61 74 20 61 63 63 65 73 73 20  ure that access 
1a680 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
1a690 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
1a6a0 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a   its associated.
1a6b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1a6c0 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69  tements] is seri
1a6d0 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51  alized.  The [SQ
1a6e0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1a6f0 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68  X] flag.** is th
1a700 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1a710 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69 73 20  or is SQLite is 
1a720 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67  configured using
1a730 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1a740 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1a750 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1a760 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1a770 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74  AD] options.** t
1a780 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
1a790 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49  g()].  The [SQLI
1a7a0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a7b0 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73   flag only makes
1a7c0 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65   a.** difference
1a7d0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
1a7e0 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b  in its default [
1a7f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
1a800 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a  RIALIZED] mode..
1a810 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1a820 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1a830 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1a840 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1a850 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1a860 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1a870 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1a880 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
1a890 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1a8a0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1a8b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a8c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1a8d0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1a8e0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1a8f0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1a900 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1a910 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1a920 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1a930 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1a940 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1a950 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1a960 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1a970 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1a980 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1a990 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1a9a0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1a9b0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1a9c0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1a9d0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1a9e0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1a9f0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
1aa00 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1aa10 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1aa20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1aa30 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1aa40 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1aa50 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1aa60 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1aa70 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1aa80 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1aa90 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1aaa0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1aab0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1aac0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
1aad0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1aae0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1aaf0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1ab00 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1ab10 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1ab20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1ab30 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1ab40 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1ab50 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1ab60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1ab70 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
1ab80 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1ab90 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1aba0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1abb0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1abc0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1abd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1abe0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1abf0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1ac00 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1ac10 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1ac20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1ac30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1ac40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1ac50 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1ac60 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1ac70 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1ac80 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1ac90 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1aca0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1acb0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1acc0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1acd0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1ace0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1acf0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1ad00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1ad10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ad20 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1ad30 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1ad40 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1ad50 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1ad60 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1ad70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1ad80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ad90 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
1ada0 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
1adb0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1adc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
1add0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
1ade0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
1adf0 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
1ae00 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
1ae10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1ae20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {H12702} The fil
1ae30 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1ae40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1ae50 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
1ae60 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
1ae70 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
1ae80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1ae90 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
1aea0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
1aeb0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1aec0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
1aed0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1aee0 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63   {H12703} A succ
1aef0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1af00 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
1af10 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1af20 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1af30 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1af40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
1af50 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
1af60 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1af70 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1af80 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
1af90 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ppDb..**.** {H12
1afa0 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
1afb0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1afc0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1afd0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1afe0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1aff0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
1b000 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1b010 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1b020 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1b030 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1b040 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1b050 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lure..**.** {H12
1b060 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1b070 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1b080 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1b090 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1b0a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b0b0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1b0c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b0d0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1b0e0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37  8..**.** {H12707
1b0f0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1b100 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1b110 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1b120 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1b130 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b140 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1b150 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1b160 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b  * {H12709} The [
1b170 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1b180 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1b190 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1b1a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b1b0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1b1c0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1b1d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1b1e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1b1f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b200 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1b210 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  REATE]..**.** {H
1b220 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1b230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1b240 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1b250 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1b260 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1b270 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1b280 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1b290 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1b2a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1b2b0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1b2c0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1b2d0 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68  * {H12712} If th
1b2e0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1b2f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b300 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1b310 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1b320 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1b330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1b340 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1b350 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b360 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1b370 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1b380 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1b390 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1b3a0 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1b3b0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1b3c0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1b3d0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1b3e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  system..**.** {H
1b3f0 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1b400 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1b410 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
1b420 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1b430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1b440 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1b450 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1b460 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1b470 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1b480 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1b490 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1b4a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1b4b0 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65   {H12714} If the
1b4c0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1b4d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1b4e0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1b4f0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1b500 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1b510 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1b520 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1b530 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1b540 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1b550 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1b560 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1b570 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1b580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1b590 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1b5a0 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  base..**.** {H12
1b5b0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1b5c0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1b5d0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1b5e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1b5f0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1b600 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1b610 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1b620 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1b630 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1b640 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1b650 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1b660 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1b670 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1b680 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1b690 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1b6a0 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1b6b0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b6c0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1b6d0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1b6e0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1b6f0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39  o>.**.** {H12719
1b700 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1b710 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1b720 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1b730 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1b740 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1b750 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1b760 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1b770 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1b780 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1b790 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1b7a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b7b0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1b7c0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1b7d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1b7e0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1b7f0 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1b800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1b810 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1b820 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1b830 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1b840 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1b850 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1b860 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1b870 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1b880 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1b890 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1b8a0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b8b0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1b8c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1b8d0 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {H12723} Two [da
1b8e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b8f0 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1b900 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1b910 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1b920 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1b930 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1b940 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1b950 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1b960 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1b970 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1b980 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1b990 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1b9a0 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1b9b0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1b9c0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1b9d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1b9e0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1b9f0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1ba00 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1ba10 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1ba20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ba30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ba40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ba50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ba60 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1ba70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ba80 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1ba90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1baa0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1bab0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1bac0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1bad0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1bae0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1baf0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1bb00 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1bb10 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1bb20 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1bb30 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1bb40 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1bb50 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1bb60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1bb70 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1bb80 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1bb90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1bba0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1bbb0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1bbc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1bbd0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1bbe0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1bbf0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1bc00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1bc10 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1bc20 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 0a  ssages {H12800}.
1bc30 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bc40 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1bc50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1bc60 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1bc70 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1bc80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1bc90 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1bca0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1bcb0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1bcc0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1bcd0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1bce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1bcf0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1bd00 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1bd10 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1bd20 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1bd30 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1bd40 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1bd50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1bd60 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1bd70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bd80 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1bd90 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1bda0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1bdb0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1bdc0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1bdd0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1bde0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1bdf0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1be00 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68  ..** Memory to h
1be10 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1be20 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1be30 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1be40 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1be50 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1be60 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1be70 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1be80 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1be90 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1bea0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1beb0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1bec0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1bed0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bee0 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1bef0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1bf00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ons..**.** If an
1bf10 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
1bf20 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
1bf30 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
1bf40 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
1bf50 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
1bf60 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
1bf70 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
1bf80 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
1bf90 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
1bfa0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
1bfb0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
1bfc0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1bfd0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31  S:.**.** {H12801
1bfe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
1bff0 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72  rrcode(D)] inter
1c000 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1c010 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20   numeric.**     
1c020 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64       [result cod
1c030 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
1c040 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1c050 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c060 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ly.**          f
1c070 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1c080 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
1c090 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1c0a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1c0b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d  ..**.** {H12803}
1c0c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
1c0d0 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71  rmsg(D)] and [sq
1c0e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44  lite3_errmsg16(D
1c0f0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
1c100 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
1c110 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1c120 65 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  e text that desc
1c130 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  ribes.**        
1c140 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74    the error in t
1c150 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74  he mostly recent
1c160 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66  ly failed interf
1c170 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20  ace call,.**    
1c180 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73        encoded as
1c190 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c1a0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1c1b0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  vely..**.** {H12
1c1c0 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73  807} The strings
1c1d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1c1e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1c1f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1c200 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
1c210 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75       are valid u
1c220 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51  ntil the next SQ
1c230 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63  Lite interface c
1c240 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  all..**.** {H128
1c250 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  08} Calls to API
1c260 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
1c270 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
1c280 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
1c290 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a         (example:
1c2a0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
1c2b0 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
1c2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e  **          chan
1c2d0 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
1c2e0 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74  e or message ret
1c2f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1c300 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
1c310 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
1c320 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1c330 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c340 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  16()]..**.** {H1
1c350 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
1c360 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73   that are not as
1c370 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1c380 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20  specific.**     
1c390 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1c3a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d  onnection] (exam
1c3b0 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20  ples:.**        
1c3c0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e    [sqlite3_mprin
1c3d0 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
1c3e0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1c3f0 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20  cache()].**     
1c400 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e       do not chan
1c410 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  ge the values re
1c420 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1c430 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1c440 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
1c450 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
1c460 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1c470 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
1c480 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1c490 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1c4a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1c4b0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1c4c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1c4d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1c4e0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1c4f0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1c500 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1c510 20 7b 48 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59   {H13000}.** KEY
1c520 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1c530 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1c540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1c550 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1c560 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1c570 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1c580 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1c590 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1c5a0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1c5b0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1c5c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c5d0 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1c5e0 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1c5f0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1c600 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1c610 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1c620 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1c630 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1c640 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1c650 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1c660 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1c670 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1c680 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c690 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1c6a0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1c6b0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1c6c0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1c6d0 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1c6e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1c6f0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1c700 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1c710 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1c720 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1c730 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1c740 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1c750 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1c760 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1c770 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1c780 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1c790 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1c7a0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1c7b0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1c7c0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1c7d0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1c7e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1c7f0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1c800 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1c810 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1c820 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1c830 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1c840 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1c850 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1c860 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1c870 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1c880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c890 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1c8a0 20 7b 48 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {H12760}.**.** 
1c8b0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1c8c0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1c8d0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1c8e0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1c8f0 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1c900 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1c910 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1c920 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1c930 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1c940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c950 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1c960 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1c970 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1c980 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1c990 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1c9a0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1c9b0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1c9c0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1c9d0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1c9e0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1c9f0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1ca00 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1ca10 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1ca20 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1ca30 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1ca40 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
1ca50 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1ca60 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1ca70 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1ca80 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1ca90 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
1caa0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1cab0 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1cac0 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70  re is a hard upp
1cad0 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20  er.** bound set 
1cae0 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  by a compile-tim
1caf0 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  e C preprocessor
1cb00 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1cb10 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1cb20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1cb30 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1cb40 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1cb50 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1cb60 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1cb70 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1cb80 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1cb90 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1cba0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1cbb0 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1cbc0 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1cbd0 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1cbe0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1cbf0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1cc00 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1cc10 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1cc20 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1cc30 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1cc40 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1cc50 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1cc60 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
1cc70 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
1cc80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
1cc90 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
1cca0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1ccb0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1ccc0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1ccd0 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1cce0 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1ccf0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1cd00 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1cd10 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1cd20 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1cd30 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1cd40 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1cd50 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1cd60 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1cd70 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1cd80 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1cd90 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1cda0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1cdb0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1cdc0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1cdd0 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1cde0 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1cdf0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1ce00 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1ce10 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1ce20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1ce30 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1ce40 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1ce50 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1ce60 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1ce70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1ce80 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1ce90 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1cea0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1ceb0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1cec0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1ced0 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1cee0 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1cef0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1cf00 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1cf10 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1cf20 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1cf30 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32  S:.**.** {H12762
1cf40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1cf50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1cf60 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68  limit(D,C,V)] wh
1cf70 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20  ere V is.**     
1cf80 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68       positive ch
1cf90 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20  anges the limit 
1cfa0 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63  on the size of c
1cfb0 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68  onstruct C in th
1cfc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
1cfd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cfe0 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73  on] D to the les
1cff0 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65  ser of V and the
1d000 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20   hard upper.**  
1d010 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e          bound on
1d020 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74   the size of C t
1d030 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f  hat is set at co
1d040 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile-time..**.*
1d050 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63  * {H12766} A suc
1d060 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1d070 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1d080 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1d090 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
1d0a0 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68         leaves th
1d0b0 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b  e state of the [
1d0c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d0d0 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64  ion] D unchanged
1d0e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d  ..**.** {H12769}
1d0f0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1d100 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1d110 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74  imit(D,C,V)] ret
1d120 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
1d130 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
1d140 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73  e limit on the s
1d150 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ize of construct
1d160 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20   C in the.**    
1d170 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1d180 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73  connection] D as
1d190 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f   it was prior to
1d1a0 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e   the call..*/.in
1d1b0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1d1c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1d1d0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1d1e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d1f0 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1d200 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39  ategories {H1279
1d210 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
1d220 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1d230 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   {limit categori
1d240 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1d250 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1d260 20 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73   various aspects
1d270 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   of a [database 
1d280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
1d290 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74  hat can be limit
1d2a0 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61  ed in size by ca
1d2b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d2c0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1d2d0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1d2e0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1d2f0 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
1d300 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
1d310 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1d320 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1d330 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
1d340 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
1d350 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
1d360 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a  e row.<dd>.**.**
1d370 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d380 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
1d390 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1d3a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
1d3b0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1d3c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1d3d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1d3e0 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1d3f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1d400 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1d410 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1d420 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1d430 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1d440 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d   SELECT or the m
1d450 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d460 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
1d470 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
1d480 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
1d490 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
1d4a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1d4b0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1d4c0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
1d4d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
1d4e0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
1d4f0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
1d500 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ession.</dd>.**.
1d510 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1d520 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1d530 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1d540 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1d550 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1d560 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1d570 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1d580 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d590 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
1d5a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d5b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1d5c0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
1d5d0 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
1d5e0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
1d5f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1d600 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d610 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1d620 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1d630 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1d640 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d650 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1d660 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1d670 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
1d680 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d690 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
1d6a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d6b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74  mum number of at
1d6c0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1d6d0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d6e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1d6f0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1d700 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1d710 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1d720 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1d730 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1d740 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20  LIKE or.** GLOB 
1d750 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a  operators.</dd>.
1d760 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1d770 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1d780 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1d790 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1d7a0 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1d7b0 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1d7c0 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1d7d0 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1d7e0 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  >.** </dl>.*/.#d
1d7f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d800 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
1d810 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
1d820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d830 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
1d840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
1d850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d860 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
1d870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1d880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d890 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1d8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d8b0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
1d8c0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1d8d0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1d8e0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
1d8f0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
1d900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d910 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
1d920 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1d930 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
1d940 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
1d950 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1d960 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
1d970 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
1d980 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
1d990 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
1d9a0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
1d9b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1d9c0 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
1d9d0 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43        9../*.** C
1d9e0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1d9f0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1da00 65 6e 74 20 7b 48 31 33 30 31 30 7d 0a 2a 2a 20  ent {H13010}.** 
1da10 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1da20 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1da30 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1da40 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1da50 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1da60 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1da70 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1da80 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1da90 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1daa0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1dab0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1dac0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1dad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1dae0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1daf0 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  ** prior call to
1db00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1db10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1db20 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1db30 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
1db40 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1db50 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1db60 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1db70 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1db80 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1db90 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1dba0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1dbb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1dbc0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1dbd0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1dbe0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1dbf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1dc00 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1dc10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1dc20 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1dc30 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
1dc40 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1dc50 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1dc60 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1dc70 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
1dc80 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1dc90 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
1dca0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1dcb0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
1dcc0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
1dcd0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
1dce0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
1dcf0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
1dd00 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
1dd10 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
1dd20 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
1dd30 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
1dd40 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
1dd50 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
1dd60 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
1dd70 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
1dd80 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
1dd90 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
1dda0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
1ddb0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
1ddc0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
1ddd0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
1dde0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
1ddf0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
1de00 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
1de10 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
1de20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
1de30 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
1de40 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
1de50 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
1de60 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
1de70 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
1de80 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
1de90 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1dea0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1deb0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
1dec0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
1ded0 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
1dee0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1def0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1df00 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
1df10 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
1df20 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1df30 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1df40 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
1df50 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
1df60 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
1df70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1df80 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1df90 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1dfa0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1dfb0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1dfc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1dfd0 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
1dfe0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1dff0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1e000 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
1e010 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
1e020 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
1e030 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
1e040 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
1e050 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
1e060 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
1e070 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
1e080 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {A13018} The cal
1e090 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1e0a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1e0b0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1e0c0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1e0d0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1e0e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e0f0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1e100 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1e110 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
1e120 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
1e130 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74   is returned, ot
1e140 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1e150 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1e160 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1e170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e180 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1e190 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1e1a0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1e1b0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1e1c0 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1e1d0 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1e1e0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1e1f0 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1e200 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1e210 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1e220 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1e230 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
1e240 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1e250 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1e260 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1e270 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1e280 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1e290 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1e2a0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1e2b0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1e2c0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1e2d0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1e2e0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1e2f0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
1e300 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
1e310 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
1e320 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
1e330 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
1e340 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
1e350 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
1e360 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
1e370 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
1e380 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
1e390 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e3a0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
1e3b0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
1e3c0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
1e3d0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
1e3e0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
1e3f0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1e400 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1e410 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1e420 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1e430 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1e440 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1e450 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1e460 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1e470 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1e480 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1e490 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1e4a0 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1e4b0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1e4c0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1e4d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1e4e0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1e4f0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1e500 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1e510 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1e520 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1e530 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1e540 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1e550 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1e560 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1e570 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1e580 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1e590 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
1e5a0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
1e5b0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
1e5c0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
1e5d0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
1e5e0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
1e5f0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
1e600 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20  s].  The legacy 
1e610 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
1e620 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
1e630 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1e640 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1e650 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
1e660 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
1e670 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
1e680 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1e690 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1e6a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
1e6b0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e   order.** to fin
1e6c0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1e6d0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1e6e0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1e6f0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1e700 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1e710 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1e720 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1e730 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1e740 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1e750 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
1e760 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1e770 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20  ** {H13011} The 
1e780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e790 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
1e7a0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1e7b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e7c0 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
1e7d0 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
1e7e0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
1e7f0 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
1e800 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
1e810 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
1e820 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20  ** {H13012} The 
1e830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e840 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
1e850 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1e860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e870 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
1e880 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
1e890 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
1e8a0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
1e8b0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
1e8c0 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
1e8d0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1e8e0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
1e8f0 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65   {H13013} If the
1e900 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1e910 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1e920 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
1e930 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
1e940 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
1e950 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
1e960 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53  than zero, the S
1e970 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20  QL text is.**   
1e980 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d         read from
1e990 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1e9a0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1e9b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1e9c0 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66  *.** {H13014} If
1e9d0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1e9e0 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1e9f0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1ea00 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
1ea10 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
1ea20 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e  ts variants is n
1ea30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1ea40 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73  n at most nBytes
1ea50 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
1ea60 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69        SQL text i
1ea70 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1ea80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d  ..**.** {H13015}
1ea90 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   In [sqlite3_pre
1eaa0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1eab0 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64  N,P,pzTail)] and
1eac0 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
1ead0 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
1eae0 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74   zSql input text
1eaf0 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74   contains more t
1eb00 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74  han one SQL stat
1eb10 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ement.**        
1eb20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20    and pzTail is 
1eb30 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a  not NULL, then *
1eb40 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1eb50 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a  o point to the.*
1eb60 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
1eb70 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
1eb80 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1eb90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1eba0 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20   zSql..**       
1ebb0 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f     <todo>What do
1ebc0 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74  es *pzTail point
1ebd0 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20   to if there is 
1ebe0 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f  one statement?</
1ebf0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  todo>.**.** {H13
1ec00 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  016} A successfu
1ec10 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1ec20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1ec30 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e  ,zSql,N,ppStmt,.
1ec40 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1ec50 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
1ec60 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69  ariants writes i
1ec70 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f  nto *ppStmt a po
1ec80 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1ec90 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
1eca0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1ecb0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
1ecc0 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e  NULL if zSql con
1ecd0 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
1ece0 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20    nothing other 
1ecf0 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20  than whitespace 
1ed00 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a  or comments..**.
1ed10 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20  ** {H13019} The 
1ed20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ed30 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1ed40 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1ed50 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
1ed60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
1ed70 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
1ed80 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
1ed90 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
1eda0 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66  .** {H13021} Bef
1edb0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
1edc0 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
1edd0 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
1ede0 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
1edf0 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
1ee00 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
1ee10 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
1ee20 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
1ee30 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ]),.**          
1ee40 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a  they first set *
1ee50 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
1ee60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1ee70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1ee80 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1ee90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1eea0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1eeb0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1eec0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1eed0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1eee0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1eef0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ef00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1ef10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ef20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1ef30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1ef40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1ef50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1ef60 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1ef70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1ef80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1ef90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1efa0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1efb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1efc0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1efd0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1efe0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1eff0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1f000 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f010 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1f020 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1f030 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1f040 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1f050 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1f060 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1f070 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1f080 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1f090 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1f0a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1f0b0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1f0c0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1f0d0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1f0e0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1f0f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f100 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1f110 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f120 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f130 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f140 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f160 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f170 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f180 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f190 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f1a0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f1b0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f1c0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f1d0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f1e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f1f0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f200 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f210 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f220 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1f240 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1f250 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1f260 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1f270 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1f280 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1f290 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1f2a0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1f2b0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f2c0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f2d0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f2e0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f2f0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f300 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f310 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f320 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f330 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1f340 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f350 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f360 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f370 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1f380 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69  * CAPIREF: Retri
1f390 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1f3a0 53 51 4c 20 7b 48 31 33 31 30 30 7d 0a 2a 2a 0a  SQL {H13100}.**.
1f3b0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1f3c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f3d0 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
1f3e0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
1f3f0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
1f400 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
1f410 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
1f420 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
1f430 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
1f440 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
1f450 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1f460 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f470 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f480 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1f490 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f4a0 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20  .** {H13101} If 
1f4b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f4c0 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20  atement] passed 
1f4d0 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  as the argument 
1f4e0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1f4f0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77  sqlite3_sql()] w
1f500 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  as compiled usin
1f510 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1f520 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f530 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1f540 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f550 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73  6_v2()], then [s
1f560 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1f570 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1f580 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    a pointer to a
1f590 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1f5a0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1f5b0 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ng a UTF-8 rende
1f5c0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
1f5d0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1f5e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f5f0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49  **.** {H13102} I
1f600 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1f610 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
1f620 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e  d as the argumen
1f630 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1f640 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
1f650 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
1f660 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f670 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f680 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1f690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f6a0 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ()], then [sqlit
1f6b0 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e  e3_sql()] return
1f6c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f6d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d  ..**.** {H13103}
1f6e0 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
1f6f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f700 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
1f710 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
1f720 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f730 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
1f740 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
1f750 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f760 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
1f770 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1f780 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1f790 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1f7a0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1f7b0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1f7c0 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d   Object {H15000}
1f7d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1f7e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1f7f0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
1f800 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f810 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
1f820 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
1f830 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
1f840 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
1f850 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
1f860 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
1f870 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1f880 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
1f890 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
1f8a0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
1f8b0 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73  t stores. Values
1f8c0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
1f8d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1f8e0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
1f8f0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
1f900 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
1f910 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
1f920 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
1f930 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1f940 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
1f950 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
1f960 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
1f970 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
1f980 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
1f990 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f9a0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
1f9b0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
1f9c0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
1f9d0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
1f9e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1f9f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
1fa00 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
1fa10 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
1fa20 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
1fa30 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
1fa40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
1fa50 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
1fa60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1fa70 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
1fa80 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
1fa90 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
1faa0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
1fab0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
1fac0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
1fad0 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
1fae0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
1faf0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1fb00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fb10 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
1fb20 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
1fb30 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1fb40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fb50 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
1fb60 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
1fb70 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
1fb80 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
1fb90 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
1fba0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
1fbb0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
1fbc0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
1fbd0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
1fbe0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
1fbf0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
1fc00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
1fc10 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
1fc20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
1fc30 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
1fc40 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
1fc50 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
1fc60 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1fc70 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1fc80 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1fc90 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
1fca0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
1fcb0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
1fcc0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
1fcd0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
1fce0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
1fcf0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1fd00 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
1fd10 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
1fd20 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1fd30 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  ween between pro
1fd40 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1fd50 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1fd60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1fd70 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
1fd80 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
1fd90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1fda0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1fdb0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
1fdc0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
1fdd0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
1fde0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
1fdf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1fe00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1fe10 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1fe20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
1fe30 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
1fe40 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
1fe50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
1fe60 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
1fe70 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
1fe80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1fe90 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
1fea0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
1feb0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
1fec0 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
1fed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
1fee0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
1fef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
1ff00 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
1ff10 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
1ff20 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
1ff30 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
1ff40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ff50 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
1ff60 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
1ff70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
1ff80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ff90 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
1ffa0 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31  ntext Object {H1
1ffb0 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6001}.**.** The 
1ffc0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
1ffd0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
1ffe0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
1fff0 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
20000 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
20010 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20  ect.  A pointer 
20020 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
20030 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
20040 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
20050 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
20060 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20070 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
20080 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
20090 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
200a0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
200b0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
200c0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
200d0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
200e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
200f0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
20100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
20110 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
20120 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
20130 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
20140 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
20150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
20160 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
20170 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
20180 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
20190 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
201a0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
201b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
201c0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
201d0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
201e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
201f0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
20200 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20210 74 73 20 7b 48 31 33 35 30 30 7d 0a 2a 2a 20 4b  ts {H13500}.** K
20220 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
20230 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
20240 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
20250 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
20260 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
20270 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
20280 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
20290 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
202a0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
202b0 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
202c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
202d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
202e0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
202f0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
20300 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
20310 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65  parameter in one
20320 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
20330 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
20340 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
20350 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
20360 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
20370 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
20380 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
20390 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
203a0 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
203b0 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
203c0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
203d0 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70  nd VVV is an alp
203e0 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
203f0 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76  eter name. The v
20400 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
20410 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
20420 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
20430 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
20440 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
20450 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
20460 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
20470 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
20480 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
20490 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
204a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
204b0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
204c0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
204d0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
204e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
204f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
20500 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
20510 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
20520 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
20530 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
20540 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
20550 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
20560 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
20570 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
20580 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d  et..** The leftm
20590 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
205a0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
205b0 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
205c0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
205d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
205e0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
205f0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
20600 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
20610 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
20620 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
20630 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
20640 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65  nce..** The inde
20650 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
20660 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
20670 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
20680 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
20690 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
206a0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
206b0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
206c0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
206d0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
206e0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
206f0 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
20700 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
20710 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
20720 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
20730 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
20740 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
20750 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
20760 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
20770 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
20780 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
20790 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
207a0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
207b0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75  .** In those rou
207c0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
207d0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
207e0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
207f0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
20800 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
20810 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
20820 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
20830 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
20840 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
20850 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
20860 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
20870 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
20880 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
20890 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
208a0 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
208b0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
208c0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
208d0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
208e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
208f0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
20900 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
20910 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
20920 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
20930 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
20940 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
20950 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
20960 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
20970 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
20980 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
20990 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
209a0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
209b0 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20  with it. If the 
209c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
209d0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
209e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
209f0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
20a00 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
20a10 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
20a20 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
20a30 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
20a40 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
20a50 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
20a60 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68  .** If the fifth
20a70 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
20a80 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
20a90 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
20aa0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
20ab0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
20ac0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
20ad0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
20ae0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
20af0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
20b00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
20b10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20b20 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
20b30 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
20b40 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
20b50 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
20b60 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
20b70 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
20b80 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
20b90 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
20ba0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
20bb0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
20bc0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
20bd0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
20be0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
20bf0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
20c00 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
20c10 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
20c20 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
20c30 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
20c40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
20c50 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
20c60 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
20c70 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20   routines..** A 
20c80 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
20c90 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
20ca0 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
20cb0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
20cc0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20cd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20ce0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
20cf0 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
20d00 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20d10 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
20d20 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
20d30 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
20d40 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
20d50 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
20d60 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
20d70 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
20d80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
20d90 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
20da0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
20db0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
20dc0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
20dd0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
20de0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
20df0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
20e00 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
20e10 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
20e20 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
20e30 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
20e40 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
20e50 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
20e60 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
20e70 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
20e80 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
20e90 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
20ea0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
20eb0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
20ec0 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
20ed0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
20ee0 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
20ef0 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
20f00 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
20f10 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
20f20 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
20f30 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
20f40 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
20f50 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
20f60 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
20f70 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
20f80 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
20f90 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
20fa0 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
20fb0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
20fc0 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
20fd0 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
20fe0 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
20ff0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
21000 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
21010 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
21020 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
21030 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
21040 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21050 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
21060 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
21070 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
21080 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
21090 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
210a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
210b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
210c0 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65  .** {H13506} The
210d0 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
210e0 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
210f0 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74  izes tokens of t
21100 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20  he forms.**     
21110 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22       "?", "?NNN"
21120 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
21130 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20  , and "@VVV" as 
21140 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a  SQL parameters,.
21150 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
21160 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
21170 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
21180 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20  more digits.**  
21190 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72          and wher
211a0 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
211b0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
211c0 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69  more alphanumeri
211d0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  c.**          ch
211e0 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
211f0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
21200 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67  owed by a string
21210 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
21220 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65          no space
21230 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
21240 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
21250 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  es..**.** {H1350
21260 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
21270 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
21280 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
21290 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d  ..**.** {H13512}
212a0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
212b0 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
212c0 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
212d0 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
212e0 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
212f0 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
21300 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
21310 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
21320 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
21330 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
21340 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
21350 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20  ** {H13515} The 
21360 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
21370 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
21380 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
21390 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NNN..**.** {H135
213a0 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
213b0 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
213c0 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
213d0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
213e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
213f0 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
21400 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
21410 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  urrences of the 
21420 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
21430 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
21440 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
21450 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
21460 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
21470 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
21480 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
21490 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
214a0 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20  occurrence.**   
214b0 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
214c0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
214d0 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
214e0 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
214f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d  ..**.** {H13521}
21500 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
21510 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
21520 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ils with an [SQL
21530 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20  ITE_RANGE].**   
21540 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20         error if 
21550 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
21560 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
21570 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20   less than 1.** 
21580 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61           or grea
21590 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d  ter than the com
215a0 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45  pile-time SQLITE
215b0 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
215c0 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  MBER.**         
215d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
215e0 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {H13524} Calls
215f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
21600 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
21610 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
21620 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
21630 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
21640 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
21650 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
21660 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
21670 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
21680 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21690 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
216a0 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {H13527} Calls
216b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
216c0 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
216d0 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
216e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
216f0 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
21700 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
21710 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
21720 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d  ..**.** {H13530}
21730 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
21740 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
21750 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
21760 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
21770 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
21780 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
21790 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
217a0 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
217b0 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {H13533} In cal
217c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
217d0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
217e0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
217f0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21800 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
21810 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
21820 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21830 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
21840 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
21850 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
21860 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
21870 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
21880 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
21890 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
218a0 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
218b0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
218c0 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
218d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
218e0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
218f0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
21900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21910 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
21920 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
21930 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
21940 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
21950 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
21960 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
21970 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
21980 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d  ..**.** {H13539}
21990 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
219a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
219b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
219c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
219d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
219e0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
219f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21a00 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
21a10 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
21a20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
21a30 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
21a40 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
21a50 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
21a60 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
21a70 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
21a80 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
21a90 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
21aa0 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
21ab0 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
21ac0 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
21ad0 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
21ae0 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inding..**.** {H
21af0 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
21b00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
21b10 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
21b20 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
21b30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21b40 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
21b50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
21b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21b70 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
21b80 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
21b90 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
21ba0 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
21bb0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
21bc0 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
21bd0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  a.**          pr
21be0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
21bf0 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65  e value V before
21c00 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
21c10 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63  ** {H13545} In c
21c20 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
21c30 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
21c40 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
21c50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21c60 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
21c70 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
21c80 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21c90 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
21ca0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
21cb0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
21cc0 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
21cd0 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
21ce0 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
21cf0 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
21d00 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
21d10 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20   V after it has 
21d20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
21d30 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  he value V..**.*
21d40 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61  * {H13548} In ca
21d50 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21d60 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
21d70 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
21d80 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
21d90 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66      is a BLOB of
21da0 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
21db0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
21dc0 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
21dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d  ..**.** {H13551}
21de0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21df0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
21e00 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61  (S,N,V)] the V a
21e10 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20  rgument may.**  
21e20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65          be eithe
21e30 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  r a [protected s
21e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
21e50 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20  ject or an.**   
21e60 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63         [unprotec
21e70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
21e80 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  e] object..*/.in
21e90 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
21ea0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21eb0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
21ec0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
21ed0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
21ee0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
21ef0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
21f00 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
21f10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
21f20 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
21f30 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
21f40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21f50 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
21f60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
21f70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
21f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
21f90 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
21fa0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
21fb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
21fc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21fd0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
21fe0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21ff0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
22000 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
22010 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22020 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
22030 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
22040 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
22050 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
22060 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22070 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
22080 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
22090 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
220a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
220b0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
220c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
220d0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
220e0 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 0a  meters {H13600}.
220f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
22100 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
22110 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
22120 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
22130 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
22140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22150 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
22160 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
22170 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
22180 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
22190 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
221a0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
221b0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
221c0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
221d0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
221e0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
221f0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
22200 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
22210 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
22220 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
22230 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
22240 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
22250 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
22260 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
22270 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
22280 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
22290 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
222a0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
222b0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
222c0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
222d0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
222e0 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  N are used,.** t
222f0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
22300 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a   in the list..**
22310 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
22320 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22330 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
22340 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
22350 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
22360 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
22370 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22380 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
22390 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
223a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20  .**.** {H13601} 
223b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
223c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
223d0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
223e0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
223f0 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20      the largest 
22400 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c  index of all SQL
22410 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74   parameters in t
22420 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
22430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22440 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53  nt] S, or 0 if S
22450 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
22460 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
22470 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22480 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
22490 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
224a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
224b0 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
224c0 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
224d0 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  20}.**.** This r
224e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
224f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
22500 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
22510 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
22520 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
22530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
22540 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
22550 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
22560 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
22570 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
22580 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
22590 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
225a0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
225b0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
225c0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
225d0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
225e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
225f0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
22600 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
22610 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
22620 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
22630 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
22640 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
22650 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
22660 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
22670 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
22680 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
22690 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
226a0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
226b0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
226c0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
226d0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
226e0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
226f0 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
22700 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
22710 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
22720 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
22730 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
22740 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
22750 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
22760 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
22770 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
22780 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
22790 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
227a0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
227b0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
227c0 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
227d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
227e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
227f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22800 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22810 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22820 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22830 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
22840 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22850 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
22860 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22870 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22880 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
22890 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
228a0 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  621} The [sqlite
228b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
228c0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
228d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
228e0 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d            a UTF-
228f0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
22900 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
22910 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a  QL parameter in.
22920 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22940 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e  ent] S having in
22950 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20  dex N, or.**    
22960 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68        NULL if th
22970 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61  ere is no SQL pa
22980 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
22990 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a  ex N or if the.*
229a0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
229b0 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
229c0 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75  N is an anonymou
229d0 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e  s parameter "?".
229e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
229f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22a00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
22a10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
22a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22a30 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
22a40 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
22a50 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30  ven Name {H13640
22a60 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
22a70 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
22a80 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
22a90 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
22aa0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
22ab0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
22ac0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
22ad0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
22ae0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
22af0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
22b00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
22b10 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
22b20 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
22b30 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
22b40 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
22b50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
22b60 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
22b70 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
22b80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
22b90 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
22ba0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
22bb0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
22bc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22bd0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
22be0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22bf0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
22c00 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
22c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22c20 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
22c30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
22c40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22c50 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
22c60 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
22c70 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b  * {H13641} The [
22c80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22c90 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
22ca0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
22cb0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
22cc0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
22cd0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  L parameter in t
22ce0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22cf0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
22d00 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
22d10 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
22d20 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
22d30 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
22d40 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
22d50 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
22d60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22d70 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
22d80 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
22d90 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
22da0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
22db0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
22dc0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
22dd0 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 0a  tement {H13660}.
22de0 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
22df0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
22e00 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
22e10 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
22e20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
22e30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22e40 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
22e50 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
22e60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73  tatement]..** Us
22e70 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
22e80 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
22e90 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
22ea0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ULL..**.** INVAR
22eb0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
22ec0 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3661} The [sqlit
22ed0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
22ee0 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  s(S)] interface 
22ef0 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a  resets all SQL.*
22f00 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
22f10 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e  eter bindings in
22f20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22f30 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b  tatement] S back
22f40 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
22f50 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
22f60 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
22f70 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
22f80 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
22f90 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
22fa0 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
22fb0 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  10}.**.** Return
22fc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22fd0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
22fe0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
22ff0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
23000 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23010 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
23020 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
23030 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
23040 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
23050 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
23060 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
23070 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
23080 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23090 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54  **.** {H13711} T
230a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
230b0 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
230c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
230d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
230e0 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73           columns
230f0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
23100 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  et generated by 
23110 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23120 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
23130 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20          or 0 if 
23140 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72  S does not gener
23150 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74  ate a result set
23160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23170 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
23180 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
23190 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
231a0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
231b0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
231c0 74 20 7b 48 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a  t {H13720}.**.**
231d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
231e0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
231f0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
23200 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
23210 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
23220 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
23230 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  T] statement.  T
23240 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
23250 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
23260 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
23270 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
23280 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
23290 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
232a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
232b0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
232c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
232d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
232e0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
232f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
23300 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
23310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23320 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
23330 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
23340 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68  T] statement. Th
23350 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
23360 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
23370 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
23380 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
23390 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
233a0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
233b0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
233c0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
233d0 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
233e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
233f0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
23400 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
23410 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
23420 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
23430 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23440 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
23450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23460 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
23470 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
23480 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
23490 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
234a0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
234b0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
234c0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
234d0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
234e0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
234f0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
23500 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
23510 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
23520 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
23530 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
23540 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
23550 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
23560 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
23570 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
23580 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
23590 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
235a0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
235b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
235c0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
235d0 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
235e0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
235f0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
23600 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
23610 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
23620 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31  S:.**.** {H13721
23630 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
23640 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
23650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23660 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
23670 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
23680 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
23690 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
236a0 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
236b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
236c0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
236d0 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  ) for the result
236e0 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20   set of the.**  
236f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
23700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
23710 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
23720 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
23730 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d  ..**.** {H13723}
23740 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
23750 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
23760 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23770 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  name16(S,N)].** 
23780 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
23790 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
237a0 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63  ame of the Nth c
237b0 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
237c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
237d0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
237e0 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c  n) for the resul
237f0 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20  t set of the.** 
23800 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23820 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
23830 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69  ated UTF-16 stri
23840 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
23850 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
23860 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
23870 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13724} The [sql
23880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23890 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
238a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
238b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
238c0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
238d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
238e0 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
238f0 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
23900 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
23910 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e   to hold their n
23920 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72  ormal return str
23930 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ings..**.** {H13
23940 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61  725} If the N pa
23950 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
23960 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23970 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
23980 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
23990 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
239a0 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  ] is out of rang
239b0 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  e, then the.**  
239c0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
239d0 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
239e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
239f0 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73 74 72  {H13726} The str
23a00 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
23a10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23a20 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a  _name(S,N)] and.
23a30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
23a40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23a50 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c  16(S,N)] are val
23a60 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
23a70 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  t.**          ca
23a80 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75  ll to either rou
23a90 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61  tine with the sa
23aa0 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d  me S and N param
23ab0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
23ac0 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69    or until [sqli
23ad0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
23ae0 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a   is called..**.*
23af0 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20  * {H13727} When 
23b00 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
23b10 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
23b20 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  atement contains
23b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
23b40 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e  AS clause, the n
23b50 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75  ame of that colu
23b60 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69  mn is the identi
23b70 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
23b80 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
23b90 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
23ba0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
23bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23bc0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
23bd0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
23be0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23bf0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
23c00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23c10 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
23c20 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
23c30 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
23c40 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 0a 2a  esult {H13740}.*
23c50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
23c60 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
23c70 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
23c80 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
23c90 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
23ca0 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
23cb0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
23cc0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
23cd0 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
23ce0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
23cf0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
23d00 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
23d10 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
23d20 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
23d30 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
23d40 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
23d50 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
23d60 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
23d70 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
23d80 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
23d90 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
23da0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
23db0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
23dc0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
23dd0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
23de0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
23df0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
23e00 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23e10 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
23e20 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
23e30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23e40 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
23e50 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
23e60 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
23e70 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
23e80 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
23e90 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
23ea0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
23eb0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
23ec0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
23ed0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
23ee0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
23ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
23f00 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
23f10 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
23f20 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
23f30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
23f40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
23f50 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
23f60 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
23f70 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
23f80 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
23f90 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
23fa0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
23fb0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
23fc0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
23fd0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
23fe0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
23ff0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
24000 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
24010 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
24020 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
24030 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
24040 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
24050 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
24060 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
24070 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
24080 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
24090 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
240a0 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
240b0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
240c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
240d0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
240e0 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
240f0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
24100 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
24110 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
24120 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
24130 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
24140 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
24150 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
24160 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
24170 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
24180 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
24190 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
241a0 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
241b0 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
241c0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
241d0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
241e0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
241f0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
24200 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
24210 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
24220 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
24230 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
24240 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
24250 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
24260 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
24270 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24280 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
24290 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
242a0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
242b0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
242c0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
242d0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
242e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
242f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24300 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
24310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24320 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
24330 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24340 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24350 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
24360 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24370 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24380 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
24390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
243a0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
243b0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
243c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
243d0 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
243e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
243f0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24400 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24410 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24430 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24440 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24450 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
24460 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
24470 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24480 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24490 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
244a0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
244b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
244c0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
244d0 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
244e0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
244f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
24500 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
24510 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
24520 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24530 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24540 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
24550 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
24560 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
24570 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24580 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24590 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
245a0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
245b0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
245c0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
245d0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
245e0 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
245f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
24600 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
24610 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24620 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24630 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
24640 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24650 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
24660 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
24670 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
24680 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24690 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
246a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
246b0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
246c0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
246d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
246e0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
246f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24700 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24710 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24720 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24730 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24740 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
24750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
24760 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
24770 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24780 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24790 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
247a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
247b0 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
247c0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
247d0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
247e0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
247f0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24800 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
24810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24820 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
24830 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
24840 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24850 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24860 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24880 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24890 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
248a0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
248b0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
248c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
248d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
248e0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
248f0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
24900 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
24910 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
24920 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
24930 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
24940 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
24950 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
24960 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
24970 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24980 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
24990 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
249a0 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
249b0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
249c0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
249d0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
249e0 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
249f0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24a00 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
24a10 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
24a20 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
24a30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
24a40 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
24a50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24a60 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24a70 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
24a80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
24a90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24aa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
24ab0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
24ac0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
24ad0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
24ae0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
24af0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
24b00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24b10 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
24b20 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
24b30 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
24b40 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
24b50 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
24b60 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
24b70 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24b80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
24b90 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
24ba0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
24bb0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
24bc0 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
24bd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24be0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24bf0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
24c00 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
24c10 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
24c20 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
24c30 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
24c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24c50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
24c60 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
24c70 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
24c80 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
24c90 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
24ca0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
24cb0 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
24cc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
24cd0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
24ce0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
24cf0 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
24d00 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
24d10 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
24d20 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
24d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24d40 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
24d50 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
24d60 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
24d70 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
24d80 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
24d90 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
24da0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
24db0 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
24dc0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
24dd0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
24de0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
24df0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24e00 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24e10 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
24e20 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
24e30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24e40 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
24e50 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
24e60 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
24e70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24e80 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
24e90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
24ea0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24eb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
24ec0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
24ed0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
24ee0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24ef0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
24f00 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
24f10 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
24f20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24f30 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
24f40 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
24f50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
24f60 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
24f70 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
24f80 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
24f90 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  60}.**.** The fi
24fa0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
24fb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24fc0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
24fd0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
24fe0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
24ff0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
25000 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
25010 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
25020 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
25030 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
25040 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
25050 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
25060 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
25070 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
25080 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
25090 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
250a0 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
250b0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
250c0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
250d0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
250e0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
250f0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
25100 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
25110 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
25120 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
25130 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
25140 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
25150 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
25160 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
25170 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
25180 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
25190 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
251a0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
251b0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
251c0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
251d0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
251e0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
251f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
25200 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
25210 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
25220 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
25230 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
25240 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
25250 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
25260 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
25270 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
25280 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
25290 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
252a0 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
252b0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
252c0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
252d0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
252e0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
252f0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
25300 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
25310 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
25320 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
25330 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
25340 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
25350 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
25360 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
25370 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
25380 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
25390 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
253a0 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
253b0 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
253c0 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
253d0 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
253e0 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
253f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
25400 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
25410 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
25420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25430 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72  type(S,N)] retur
25440 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
25450 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
25460 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
25470 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
25480 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a  clared datatype.
25490 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
254a0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
254b0 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 73   that appears as
254c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
254d0 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20  (numbered.**    
254e0 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f         from 0) o
254f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
25500 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
25510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
25520 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20  **.** {H13762}  
25530 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25540 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
25550 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
25560 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
25570 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
25580 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
25590 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
255a0 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20  order string.** 
255b0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69            contai
255c0 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
255d0 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  d datatype of th
255e0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
255f0 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20  hat appears.**  
25600 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
25610 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
25620 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20  ered from 0) of 
25630 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74  the result set t
25640 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
25650 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
25660 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
25670 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20   {H13763}  If N 
25680 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f  is less than 0 o
25690 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 74  r N is greater t
256a0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a  han or equal to.
256b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
256c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
256d0 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  ns in the [prepa
256e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
256f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ,.**           o
25700 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
25710 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
25720 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
25730 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
25740 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
25750 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f   table column, o
25760 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
25770 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
25780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
25790 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f  curs during enco
257a0 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73  ding conversions
257b0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
257c0 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71      calls to [sq
257d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
257e0 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  ltype(S,N)] or.*
257f0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
25800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25810 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74  type16(S,N)] ret
25820 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e  urn NULL..*/.con
25830 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25840 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25850 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25860 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
25870 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
25880 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
25890 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
258a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
258b0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
258c0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30  Statement {H1320
258d0 30 7d 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0}.**.** After a
258e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
258f0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
25900 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
25910 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
25920 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
25930 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25940 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
25950 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
25960 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
25970 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
25980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
25990 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
259a0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
259b0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
259c0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
259d0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
259e0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
259f0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
25a00 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
25a10 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
25a20 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
25a30 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
25a40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
25a50 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
25a60 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
25a70 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
25a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
25a90 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25aa0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
25ab0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
25ac0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
25ad0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
25ae0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
25af0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
25b00 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
25b10 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
25b20 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
25b30 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
25b40 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
25b50 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
25b60 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
25b70 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
25b80 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
25b90 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
25ba0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
25bb0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
25bc0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
25bd0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
25be0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
25bf0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
25c00 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
25c10 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
25c20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25c30 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
25c40 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
25c50 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
25c60 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
25c70 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
25c80 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
25c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
25ca0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
25cb0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
25cc0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
25cd0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
25ce0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
25cf0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
25d00 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
25d10 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
25d20 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
25d30 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
25d40 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
25d50 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
25d60 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
25d70 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
25d80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
25d90 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
25da0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
25db0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
25dc0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
25dd0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
25de0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
25df0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
25e00 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b  tinuing..**.** [
25e10 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
25e20 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
25e30 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
25e40 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
25e50 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
25e60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
25e70 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
25e80 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
25e90 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
25ea0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
25eb0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
25ec0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
25ed0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
25ee0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
25ef0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
25f00 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  state..**.** If 
25f10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
25f20 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
25f30 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
25f40 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
25f50 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
25f60 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
25f70 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
25f80 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
25f90 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
25fa0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
25fb0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
25fc0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
25fd0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
25fe0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
25ff0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
26000 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
26010 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
26020 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
26030 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
26040 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
26050 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
26060 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
26070 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
26080 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
26090 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
260a0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
260b0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
260c0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
260d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
260e0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
260f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
26100 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
26110 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
26120 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
26130 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
26140 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
26150 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
26160 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
26170 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
26180 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
26190 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
261a0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
261b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
261c0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
261d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
261e0 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
261f0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
26200 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
26210 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
26220 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
26230 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
26240 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
26250 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
26260 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
26270 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
26280 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
26290 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
262a0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
262b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
262c0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
262d0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
262e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
262f0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
26300 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
26310 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
26320 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
26330 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
26340 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
26350 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
26360 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
26370 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
26380 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
26390 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
263a0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
263b0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
263c0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
263d0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
263e0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
263f0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
26400 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
26410 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
26420 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
26430 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
26440 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
26450 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
26460 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
26470 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
26480 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
26490 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
264a0 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
264b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
264c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
264d0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
264e0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
264f0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
26500 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
26510 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
26520 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
26530 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
26540 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
26550 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
26560 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
26570 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
26580 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
26590 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
265a0 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
265b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
265c0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
265d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
265e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
265f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
26600 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
26610 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
26620 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
26630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26640 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
26650 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
26660 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
26670 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
26680 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
26690 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
266a0 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
266b0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
266c0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
266d0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ded..**.** INVAR
266e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
266f0 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70  3202}  If the [p
26700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26710 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74 6f  t] S is ready to
26720 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a   be run, then.**
26730 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
26740 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76  te3_step(S)] adv
26750 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70 61  ances that prepa
26760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e  red statement un
26770 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  til.**          
26780 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75   completion or u
26790 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79  ntil it is ready
267a0 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
267b0 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a  er row of the.**
267c0 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c             resul
267d0 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20  t set, or until 
267e0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
267f0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
26800 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
26810 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
26820 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
26830 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e  * {H15304}  When
26840 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
26850 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75  te3_step(S)] cau
26860 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ses the [prepare
26870 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
26880 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20 72            S to r
26890 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
268a0 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  , the function r
268b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
268c0 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ONE]..**.** {H15
268d0 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  306}  When a cal
268e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
268f0 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63  ep(S)] stops bec
26900 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79  ause it is ready
26910 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
26920 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
26930 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
26940 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e  t set, it return
26950 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a  s [SQLITE_ROW]..
26960 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20  **.** {H15308}  
26970 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
26980 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65  lite3_step(S)] e
26990 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20  ncounters an.** 
269a0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
269b0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
269c0 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
269d0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a  un-time error,.*
269e0 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20 72  *           it r
269f0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
26a00 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65  riate error code
26a10 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65   that is not one
26a20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
26a30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53   [SQLITE_OK], [S
26a40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b  QLITE_ROW], or [
26a50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a  SQLITE_DONE]..**
26a60 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66  .** {H15310}  If
26a70 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
26a80 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
26a90 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
26aa0 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
26ab0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
26ac0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
26ad0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
26ae0 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
26af0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
26b00 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
26b10 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
26b20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
26b30 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
26b40 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
26b50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
26b60 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
26b70 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
26b80 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  on returns eithe
26b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
26ba0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b  SQLITE_ERROR], [
26bb0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72  SQLITE_BUSY], or
26bc0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
26bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26be0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
26bf0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
26c00 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
26c10 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
26c20 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30  sult set {H13770
26c30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  }.**.** Returns 
26c40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  the number of va
26c50 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72  lues in the curr
26c60 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
26c70 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  esult set..**.**
26c80 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26c90 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74  ** {H13771}  Aft
26ca0 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  er a call to [sq
26cb0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74  lite3_step(S)] t
26cc0 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  hat returns [SQL
26cd0 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20  ITE_ROW],.**    
26ce0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
26cf0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
26d00 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  )] routine will 
26d10 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20  return the same 
26d20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
26d30 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74     as the [sqlit
26d40 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
26d50 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  S)] function..**
26d60 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66  .** {H13772}  Af
26d70 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
26d80 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e  p(S)] has return
26d90 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ed any value oth
26da0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
26db0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
26dc0 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c  ] or before [sql
26dd0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
26de0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  s been called on
26df0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26e00 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
26e10 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66  ement] for the f
26e20 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20  irst time since 
26e30 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  it was.**       
26e40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
26e50 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
26e60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
26e70 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20  et | reset],.** 
26e80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
26e90 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
26ea0 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  t(S)] routine re
26eb0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69  turns zero..*/.i
26ec0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
26ed0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
26ee0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26ef0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
26f00 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
26f10 65 73 20 7b 48 31 30 32 36 35 7d 0a 2a 2a 20 4b  es {H10265}.** K
26f20 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
26f30 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
26f40 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
26f50 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
26f60 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
26f70 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
26f80 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
26f90 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
26fa0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
26fb0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
26fc0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
26fd0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
26fe0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
26ff0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
27000 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
27010 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
27020 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
27030 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
27040 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
27050 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
27060 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
27070 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
27080 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
27090 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
270a0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
270b0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
270c0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
270d0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
270e0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
270f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
27100 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
27110 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
27120 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
27130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27140 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
27150 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
27160 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27170 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
27180 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
27190 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
271a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
271b0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
271c0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
271d0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
271e0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
271f0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
27200 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
27210 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
27220 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
27230 7b 48 31 33 38 30 30 7d 0a 2a 2a 20 4b 45 59 57  {H13800}.** KEYW
27240 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
27250 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
27260 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27270 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
27280 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
27290 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
272a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
272b0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
272c0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
272d0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
272e0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
272f0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
27300 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73  y.  In every cas
27310 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
27320 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
27330 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
27340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27350 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
27360 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
27370 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
27380 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
27390 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
273a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
273b0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
273c0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
273d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
273e0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
273f0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
27400 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
27410 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
27420 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
27430 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
27440 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27450 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
27460 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
27470 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
27480 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
27490 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
274a0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
274b0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
274c0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
274d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
274e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
274f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
27500 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
27510 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
27520 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27530 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27540 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
27550 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
27560 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
27570 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
27580 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27590 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
275a0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
275b0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
275c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
275d0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
275e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
275f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
27600 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
27610 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
27620 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
27630 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
27640 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
27650 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
27660 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27670 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
27680 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
27690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
276a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
276b0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
276c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
276d0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
276e0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
276f0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
27700 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
27710 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
27720 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27730 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
27740 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
27750 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
27760 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
27770 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
27780 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
27790 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
277a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
277b0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
277c0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
277d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
277e0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
277f0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
27800 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
27810 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
27820 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
27830 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
27840 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27850 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
27860 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
27870 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
27880 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
27890 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
278a0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
278b0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
278c0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
278d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
278e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
278f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
27900 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
27910 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
27920 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
27930 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
27940 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
27950 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
27960 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
27970 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
27980 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
27990 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
279a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
279b0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
279c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
279d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
279e0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
279f0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
27a00 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
27a10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
27a20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
27a30 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
27a40 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
27a50 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
27a60 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
27a70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27a80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
27a90 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
27aa0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
27ab0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27ac0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
27ad0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
27ae0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
27af0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
27b00 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
27b10 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
27b20 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
27b30 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
27b40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
27b50 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
27b60 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
27b70 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
27b80 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
27b90 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
27ba0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
27bb0 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
27bc0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
27bd0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
27be0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
27bf0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
27c00 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
27c10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
27c20 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
27c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27c40 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
27c50 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
27c60 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
27c70 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
27c80 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
27c90 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
27ca0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
27cb0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
27cc0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
27cd0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
27ce0 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
27cf0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
27d00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
27d10 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
27d20 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
27d30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27d40 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
27d50 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
27d60 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
27d70 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27d80 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
27d90 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  F-8..** The zero
27da0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
27db0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
27dc0 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
27dd0 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
27de0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
27df0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
27e00 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
27e10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27e20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
27e30 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
27e40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27e50 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
27e60 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
27e70 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
27e80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
27e90 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
27ea0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
27eb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27ec0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
27ed0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
27ee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
27ef0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
27f00 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
27f10 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
27f20 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
27f30 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
27f40 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
27f50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
27f60 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
27f70 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
27f80 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27f90 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
27fa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
27fb0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
27fc0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
27fd0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
27fe0 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
27ff0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
28000 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
28010 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
28020 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
28030 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
28040 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
28050 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
28060 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
28070 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
28080 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
28090 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
280a0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
280b0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
280c0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
280d0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
280e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
280f0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
28100 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
28110 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
28120 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
28130 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
28140 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
28150 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
28160 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
28170 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
28180 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28190 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
281a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
281b0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
281c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
281d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
281e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
281f0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28200 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28210 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
28220 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
28230 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28240 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
28250 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
28260 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
28270 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
28280 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28290 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
282a0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
282b0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
282c0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
282d0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
282e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
282f0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
28300 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
28310 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
28320 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
28330 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
28340 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
28350 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
28360 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28370 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
28380 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
28390 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
283a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
283b0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
283c0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
283d0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
283e0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
283f0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
28400 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
28410 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
28420 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
28430 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
28440 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28450 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
28460 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
28470 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
28480 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28490 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
284a0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
284b0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
284c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
284d0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
284e0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
284f0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
28500 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
28510 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28520 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
28530 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
28540 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
28550 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
28560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
28570 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
28580 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
28590 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
285a0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
285b0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
285c0 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
285d0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
285e0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
285f0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
28600 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
28610 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
28620 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
28630 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
28640 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
28650 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
28660 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
28670 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
28680 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
28690 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
286a0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
286b0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
286c0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
286d0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
286e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
286f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
28700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28710 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
28720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28730 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
28740 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
28750 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
28760 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
28770 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
28780 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
28790 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
287a0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
287b0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
287c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
287d0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
287e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
287f0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
28800 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28810 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
28820 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
28830 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
28840 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
28850 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
28860 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
28870 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
28880 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
28890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
288a0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
288b0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
288c0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
288d0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
288e0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
288f0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
28900 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
28910 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28920 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
28930 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
28940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28950 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
28960 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28970 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
28980 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
28990 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
289a0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
289b0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
289c0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
289d0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
289e0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
289f0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
28a00 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
28a10 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
28a20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
28a30 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
28a40 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
28a50 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
28a60 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
28a70 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
28a80 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
28a90 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
28aa0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
28ab0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
28ac0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
28ad0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
28ae0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
28af0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
28b00 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
28b10 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
28b20 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
28b30 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
28b40 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
28b50 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
28b60 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
28b70 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
28b80 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
28b90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
28ba0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
28bb0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
28bc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
28bd0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
28be0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28bf0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
28c00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28c10 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
28c20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28c30 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
28c40 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
28c50 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
28c60 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
28c70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28c80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
28c90 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
28ca0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
28cb0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
28cc0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
28cd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28ce0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
28cf0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28d00 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
28d10 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
28d20 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
28d30 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
28d40 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
28d50 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
28d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28d70 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
28d80 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
28d90 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
28da0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
28db0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28dc0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
28dd0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
28de0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
28df0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28e00 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
28e10 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
28e20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
28e30 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
28e40 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
28e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28e60 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
28e70 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
28e80 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
28e90 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
28ea0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
28eb0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
28ec0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
28ed0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
28ee0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28ef0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
28f00 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
28f10 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
28f20 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
28f30 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
28f40 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
28f50 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
28f60 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
28f70 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
28f80 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
28f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28fa0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
28fb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
28fc0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
28fd0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
28fe0 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
28ff0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
29000 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
29010 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
29020 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
29030 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
29040 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
29050 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
29060 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
29070 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
29080 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
29090 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
290a0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
290b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
290c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
290d0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
290e0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
290f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
29100 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
29110 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
29120 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3803} The [sqlit
29130 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53  e3_column_blob(S
29140 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29150 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29160 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29170 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29180 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29190 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
291a0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
291b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
291c0 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   S into a BLOB a
291d0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
291e0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
291f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
29200 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
29210 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65  .** {H13806} The
29220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29230 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74  _bytes(S,N)] int
29240 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29250 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
29260 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29270 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  n the BLOB or st
29280 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
29290 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
292a0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
292b0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
292c0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
292d0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
292e0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
292f0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
29300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
29310 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
29320 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
29330 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e  lumn_text(S,N)].
29340 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20  .**.** {H13809} 
29350 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29360 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29  umn_bytes16(S,N)
29370 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29380 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
29390 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
293a0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
293b0 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
293c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
293d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
293e0 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
293f0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
29400 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
29410 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
29420 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29430 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
29440 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
29450 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  812} The [sqlite
29460 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
29470 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
29480 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
29490 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
294a0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
294b0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
294c0 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
294d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
294e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
294f0 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  ] S into a float
29500 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
29510 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
29520 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29530 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
29540 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65  .** {H13815} The
29550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29560 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72  _int(S,N)] inter
29570 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
29580 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
29590 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
295a0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
295b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
295c0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
295d0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
295e0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
295f0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29600 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
29610 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
29620 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
29630 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
29640 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20  .**.** {H13818} 
29650 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29660 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
29670 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
29680 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
29690 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
296a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
296b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
296c0 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
296d0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
296e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
296f0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
29700 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
29710 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
29720 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
29730 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
29740 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73   {H13821} The [s
29750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29760 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  xt(S,N)] interfa
29770 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
29780 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
29790 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
297a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
297b0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
297c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
297d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
297e0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
297f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
29800 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
29810 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
29820 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
29830 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
29840 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20  ** {H13824} The 
29850 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29860 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74  text16(S,N)] int
29870 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29890 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
298a0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
298b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
298c0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
298d0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
298e0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
298f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
29900 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
29910 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
29920 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
29930 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64  order string and
29940 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
29950 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
29960 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
29970 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68  *.** {H13827} Th
29980 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29990 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
299a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
299b0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
299c0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
299d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
299e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
299f0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
29a00 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
29a10 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
29a20 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
29a30 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
29a40 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
29a50 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29a60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29a70 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29a80 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29a90 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
29aa0 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65  .** {H13830} The
29ab0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29ac0 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
29ad0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
29af0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72  nter to an [unpr
29b00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29b10 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
29b20 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29b30 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
29b40 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29b50 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29b60 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29b70 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29b80 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
29b90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
29bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29bc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
29bd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29be0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
29bf0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29c00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29c10 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
29c20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29c30 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
29c40 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
29c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29c60 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
29c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
29c80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29c90 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
29ca0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
29cb0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
29cc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29cd0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
29ce0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
29cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29d00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29d10 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
29d20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29d30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
29d40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29d50 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
29d60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
29d70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29d80 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
29d90 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
29da0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
29db0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29dc0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
29dd0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
29de0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
29df0 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
29e00 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  300}.**.** The s
29e10 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29e20 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
29e30 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
29e40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29e50 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ment]..** If the
29e60 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
29e70 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
29e80 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
29e90 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
29ea0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
29eb0 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65  s returned. If e
29ec0 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
29ed0 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
29ee0 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
29ef0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
29f00 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
29f10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
29f20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
29f30 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
29f40 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
29f50 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
29f60 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
29f70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29f80 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
29f90 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
29fa0 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
29fb0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
29fc0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
29fd0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
29fe0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
29ff0 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
2a000 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
2a010 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
2a020 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65  ]..** Incomplete
2a030 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20   updates may be 
2a040 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20  rolled back and 
2a050 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e  transactions can
2a060 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64  celed,.** depend
2a070 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75  ing on the circu
2a080 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68  mstances, and th
2a090 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  e.** [error code
2a0a0 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20  ] returned will 
2a0b0 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  be [SQLITE_ABORT
2a0c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
2a0d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  NTS:.**.** {H113
2a0e0 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
2a0f0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e  _finalize(S)] in
2a100 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73  terface destroys
2a110 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a120 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a130 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65  ment] S and rele
2a140 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ases all.**     
2a150 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20       memory and 
2a160 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68  file resources h
2a170 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65  eld by that obje
2a180 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  ct..**.** {H1130
2a190 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a1a0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a1b0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a1c0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a1d0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a1e0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a1f0 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a  ned an error,.**
2a200 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2a210 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a220 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61  (S)] returns tha
2a230 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f  t same error..*/
2a240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
2a250 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2a260 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a270 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2a280 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2a290 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
2a2a0 48 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  H13330}.**.** Th
2a2b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2a2c0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2a2d0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2a2e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a2f0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2a300 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2a310 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2a320 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2a330 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74  d..** Any SQL st
2a340 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2a350 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2a360 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2a370 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2a380 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2a390 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2a3a0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2a3b0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2a3c0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2a3d0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2a3e0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2a3f0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ings..**.** {H11
2a400 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  332} The [sqlite
2a410 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2a420 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2a430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a440 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20  ment] S.**      
2a450 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20      back to the 
2a460 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2a470 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2a480 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20  {H11334} If the 
2a490 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2a4a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a4b0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2a4c0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2a4d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a4e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2a4f0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2a500 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
2a510 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
2a520 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2a530 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2a540 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2a550 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2a560 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a570 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2a580 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
2a590 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  H11336} If the m
2a5a0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2a5b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2a5c0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2a5d0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a5e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a5f0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2a600 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
2a610 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2a620 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2a630 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
2a640 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2a650 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20  ** {H11338} The 
2a660 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2a670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2a680 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2a690 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
2a6a0 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
2a6b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2a6c0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2a6d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a6e0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2a6f0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2a700 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2a710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a720 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2a730 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2a740 6f 6e 73 20 7b 48 31 36 31 30 30 7d 0a 2a 2a 20  ons {H16100}.** 
2a750 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
2a760 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2a770 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
2a780 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2a790 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2a7a0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
2a7b0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2a7c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2a7d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
2a7e0 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ese two function
2a7f0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
2a800 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
2a810 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2a820 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
2a830 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
2a840 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2a850 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
2a860 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
2a870 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
2a880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2a890 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
2a8a0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
2a8b0 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a  ce between the.*
2a8c0 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68  * two is that th
2a8d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2a8e0 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  er, the name of 
2a8f0 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e  the (scalar) fun
2a900 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2a910 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65  egate, is encode
2a920 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73  d in UTF-8 for s
2a930 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a940 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46  nction() and UTF
2a950 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  -16.** for sqlit
2a960 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a970 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
2a980 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2a990 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2a9a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2a9b0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2a9c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2a9d0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20  o be added.  If 
2a9e0 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d  a single program
2a9f0 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2aa00 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2aa10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72  connection inter
2aa20 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20  nally, then SQL 
2aa30 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
2aa40 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
2aa50 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20  ally to.** each 
2aa60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2aa70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
2aa80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2aa90 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2aaa0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2aab0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
2aac0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
2aad0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
2aae0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
2aaf0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
2ab00 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
2ab10 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
2ab20 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
2ab30 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
2ab40 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
2ab50 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
2ab60 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d  ters.  Any attem
2ab70 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2ab80 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2ab90 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2aba0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2abb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e  LITE_ERROR] bein
2abc0 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2abd0 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  * The third para
2abe0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d  meter is the num
2abf0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2ac00 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
2ac10 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2ac20 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66  regate takes. If
2ac30 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
2ac40 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2ac50 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
2ac60 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2ac70 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
2ac80 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2ac90 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nts..**.** The f
2aca0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
2acb0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
2acc0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
2acd0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
2ace0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
2acf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
2ad00 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
2ad10 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
2ad20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2ad30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
2ad40 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
2ad50 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
2ad60 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2ad70 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2ad80 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2ad90 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2ada0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2adb0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2adc0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2add0 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64  .  It is allowed
2ade0 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
2adf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae00 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
2ae10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ae20 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
2ae30 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
2ae40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2ae50 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2ae60 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
2ae70 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d  xtRep..** When m
2ae80 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2ae90 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2aea0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
2aeb0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
2aec0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
2aed0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
2aee0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
2aef0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
2af00 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
2af10 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
2af20 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
2af30 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
2af40 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
2af50 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
2af60 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
2af70 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
2af80 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
2af90 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
2afa0 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   The fifth param
2afb0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
2afc0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
2afd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2afe0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
2aff0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
2b000 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
2b010 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
2b020 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2b030 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ..**.** The seve
2b040 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
2b050 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
2b060 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
2b070 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
2b080 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
2b090 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
2b0a0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
2b0b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2b0c0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2b0d0 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c  te. A scalar SQL
2b0e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b0f0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2b100 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e  tion of the xFun
2b110 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e  c.** callback on
2b120 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ly, NULL pointer
2b130 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  s should be pass
2b140 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
2b150 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
2b160 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67  rameters. An agg
2b170 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2b180 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2b190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2b1a0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
2b1b0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
2b1c0 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
2b1d0 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65  for xFunc. To de
2b1e0 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2b1f0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2b200 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2b210 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c  ass NULL for all
2b220 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20   three function 
2b230 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2b240 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
2b250 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2b260 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2b270 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2b280 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2b290 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2b2a0 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2b2b0 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2b2c0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2b2d0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2b2e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2b2f0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
2b300 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2b310 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2b320 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
2b330 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2b340 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2b350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2b360 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  sed..**.** INVAR
2b370 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2b380 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6103} The [sqlit
2b390 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b3a0 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  on16()] interfac
2b3b0 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74 6c  e behaves exactl
2b3c0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69  y.**          li
2b3d0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ke [sqlite3_crea
2b3e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69  te_function()] i
2b3f0 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65  n every way exce
2b400 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20  pt that it.**   
2b410 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74         interpret
2b420 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e  s the zFunctionN
2b430 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 20  ame argument as 
2b440 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2b450 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20  UTF-16.**       
2b460 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f     native byte o
2b470 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
2b480 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2b490 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  ed UTF-8..**.** 
2b4a0 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65  {H16106} A succe
2b4b0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
2b4c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2b4d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2b4e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2b4f0 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,N,E,...)] inter
2b500 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a  face registers.*
2b510 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65  *          or re
2b520 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20  places callback 
2b530 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
2b540 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b550 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
2b560 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70       used to imp
2b570 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
2b580 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
2b590 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72  with N parameter
2b5a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
2b5b0 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65  d having a prefe
2b5c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2b5d0 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  ng of E..**.** {
2b5e0 48 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73  H16109} A succes
2b5f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2b600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b610 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2b620 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2b630 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65      replaces the
2b640 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20   P, F, S, and L 
2b650 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20  values from any 
2b660 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
2b670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2b680 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61   same D, X, N, a
2b690 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  nd E values..**.
2b6a0 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20  ** {H16112} The 
2b6b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b6c0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
2b6d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2b6e0 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ls with.**      
2b6f0 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64      a return cod
2b700 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52  e of [SQLITE_ERR
2b710 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66  OR] if the SQL f
2b720 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  unction name X i
2b730 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f  s.**          lo
2b740 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79  nger than 255 by
2b750 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66  tes exclusive of
2b760 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2b770 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ator..**.** {H16
2b780 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75  118} Either F mu
2b790 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53  st be NULL and S
2b7a0 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e   and L are non-N
2b7b0 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a  ULL or else F.**
2b7c0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
2b7d0 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20  -NULL and S and 
2b7e0 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65  L are NULL, othe
2b7f0 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  rwise.**        
2b800 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2b810 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2b820 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74  ,E,P,F,S,L)] ret
2b830 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52  urns [SQLITE_ERR
2b840 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  OR]..**.** {H161
2b850 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
2b860 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b870 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
2b880 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2b890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2b8a0 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2b8b0 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72  TE_BUSY] if ther
2b8c0 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65  e exist [prepare
2b8d0 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
2b8e0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
2b8f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2b900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b910 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
2b920 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6124} The [sqlit
2b930 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b940 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69  on(D,X,N,...)] i
2b950 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2b960 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
2b970 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
2b980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2b990 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28  if parameter N (
2b9a0 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e  specifying the n
2b9b0 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
2b9c0 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74    of arguments t
2b9d0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
2b9e0 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65  on being registe
2b9f0 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20  red) is less.** 
2ba00 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31           than -1
2ba10 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2ba20 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36   127..**.** {H16
2ba30 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e  127} When N is n
2ba40 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
2ba50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ba60 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ba70 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2ba80 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
2ba90 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
2baa0 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
2bab0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
2bac0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
2bad0 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d  d X when the num
2bae0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2baf0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
2bb00 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20  tion is.**      
2bb10 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a      exactly N..*
2bb20 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68  *.** {H16130} Wh
2bb30 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20  en N is -1, the 
2bb40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bb50 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2bb60 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2bb70 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2bb80 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
2bb90 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2bba0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
2bbb0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2bbc0 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62   X with any numb
2bbd0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
2bbe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20  .**.** {H16133} 
2bbf0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
2bc00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bc10 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2bc20 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2bc30 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2bc40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2bc50 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2bc60 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20  tion X.**       
2bc70 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20     and when one 
2bc80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68  implementation h
2bc90 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20  as N>=0 and the 
2bca0 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29  other has N=(-1)
2bcb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2bcc0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2bcd0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
2bce0 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a  N is preferred..
2bcf0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57  **.** {H16136} W
2bd00 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2bd10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bd20 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e  ction(D,X,N,E,..
2bd30 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2bd40 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
2bd50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2bd60 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2bd70 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20  ction X with.** 
2bd80 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
2bd90 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2bda0 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68  ments N but with
2bdb0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20   different.**   
2bdc0 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73         encodings
2bdd0 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70   E, then the imp
2bde0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72  lementation wher
2bdf0 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a  e E matches the.
2be00 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
2be10 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
2be20 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
2be30 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61  * {H16139} For a
2be40 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2be50 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64  function created
2be60 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2be70 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2be80 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2be90 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68  N,E,P,0,S,L)] th
2bea0 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20  e finalizer.**  
2beb0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2bec0 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62   L will always b
2bed0 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c  e invoked exactl
2bee0 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a  y once if the.**
2bef0 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66            step f
2bf00 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c  unction S is cal
2bf10 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
2bf20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  times..**.** {H1
2bf30 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74  6142} When SQLit
2bf40 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72  e invokes either
2bf50 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53   the xFunc or xS
2bf60 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a  tep function of.
2bf70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61  **          an a
2bf80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bf90 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2bfa0 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65  or aggregate cre
2bfb0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2bfc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   by [sqlite3_cre
2bfd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2bfe0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2bff0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2c000 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
2c010 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20  en the array of 
2c020 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c030 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61  objects passed a
2c040 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c050 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65    third paramete
2c060 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72  r are always [pr
2c070 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c080 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2c090 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2c0a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2c0b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2c0c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2c0d0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2c0e0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2c0f0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2c100 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2c110 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2c120 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c130 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c140 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2c150 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2c160 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2c170 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2c180 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2c190 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2c1a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c1b0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2c1c0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2c1d0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2c1e0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2c1f0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c200 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2c210 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2c220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c230 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c240 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c250 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2c260 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c270 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c280 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2c290 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2c2a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c2b0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
2c2c0 67 73 20 7b 48 31 30 32 36 37 7d 0a 2a 2a 0a 2a  gs {H10267}.**.*
2c2d0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2c2e0 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
2c2f0 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
2c300 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
2c310 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
2c320 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
2c330 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
2c340 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
2c350 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
2c360 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
2c370 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
2c380 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
2c390 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
2c3a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
2c3b0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
2c3c0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
2c3d0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
2c3e0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
2c3f0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
2c400 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2c410 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
2c420 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c430 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
2c440 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
2c450 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
2c460 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
2c470 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74 65  PI3REF: Obsolete
2c480 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
2c490 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2c4a0 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62 73   are all now obs
2c4b0 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65 72  olete.  In order
2c4c0 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
2c4d0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2c4e0 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
2c4f0 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e 74  er code, we cont
2c500 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74 0a  inue to support.
2c510 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
2c520 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ns.  However, ne
2c530 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 72  w development pr
2c540 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61 76  ojects should av
2c550 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
2c560 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2c570 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
2c580 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
2c590 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
2c5a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
2c5b0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
2c5c0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e   to tell you wan
2c5d0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69 6e  t they do..*/.in
2c5e0 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  t sqlite3_aggreg
2c5f0 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ate_count(sqlite
2c600 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e 74  3_context*);.int
2c610 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
2c620 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2c630 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61  .int sqlite3_tra
2c640 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2c650 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2c660 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e  lite3_stmt*);.in
2c670 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
2c680 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
2c690 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2c6a0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2c6b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  );.int sqlite3_m
2c6c0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2c6d0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2c6e0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2c6f0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2c700 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c710 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
2c720 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
2c730 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
2c740 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  100}.**.** The C
2c750 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
2c760 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
2c770 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2c780 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
2c790 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
2c7a0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
2c7b0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
2c7c0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
2c7d0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
2c7e0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
2c7f0 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
2c800 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
2c810 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
2c820 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
2c830 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
2c840 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2c850 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2c860 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2c870 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2c880 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
2c890 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
2c8a0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2c8b0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2c8c0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
2c8d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2c8e0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
2c8f0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
2c900 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
2c910 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c920 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
2c930 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
2c940 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c950 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
2c960 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2c970 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
2c980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2c990 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
2c9a0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
2c9b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2c9c0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2c9d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2c9e0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
2c9f0 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
2ca00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ca10 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
2ca20 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
2ca30 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
2ca40 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2ca50 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
2ca60 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
2ca70 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
2ca80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
2ca90 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2caa0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2cab0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2cac0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2cad0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2cae0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2caf0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2cb00 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2cb10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2cb20 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2cb30 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2cb40 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2cb50 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2cb60 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2cb70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2cb80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2cb90 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2cba0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
2cbb0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
2cbc0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
2cbd0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
2cbe0 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
2cbf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cc00 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
2cc10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2cc20 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2cc30 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
2cc40 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
2cc50 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
2cc60 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
2cc70 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
2cc80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2cc90 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2cca0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2ccb0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2ccc0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2ccd0 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2cce0 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2ccf0 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2cd00 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2cd10 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2cd20 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2cd30 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2cd40 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2cd50 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2cd60 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2cd70 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2cd80 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2cd90 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2cda0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2cdb0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2cdc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2cdd0 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2cde0 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2cdf0 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2ce00 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2ce10 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2ce20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2ce30 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2ce40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
2ce50 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
2ce60 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
2ce70 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
2ce80 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
2ce90 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
2cea0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2ceb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2cec0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
2ced0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2cee0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
2cef0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
2cf00 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
2cf10 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2cf20 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2cf30 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2cf40 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
2cf50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cf60 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2cf70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2cf80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
2cf90 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2cfa0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2cfb0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
2cfc0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2cfd0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
2cfe0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
2cff0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
2d000 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  rs..**.** INVARI
2d010 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ANTS:.**.** {H15
2d020 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
2d030 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
2d040 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d050 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d060 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d080 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c  ject V into a BL
2d090 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20  OB and then.**  
2d0a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2d0b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d0c0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2d0d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d  ..**.** {H15106}
2d0e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d0f0 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
2d100 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d110 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d120 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d130 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
2d140 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2d150 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2d160 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2d170 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2d180 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2d190 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2d1a0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2d1b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2d1c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2d1d0 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
2d1e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
2d1f0 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
2d200 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b  * {H15109} The [
2d210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d220 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
2d230 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
2d240 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
2d250 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d260 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
2d270 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
2d280 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
2d290 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
2d2a0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
2d2b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2d2c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
2d2d0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2d2e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d2f0 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
2d300 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d310 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2d320 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
2d330 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
2d340 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  )]..**.** {H1511
2d350 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d360 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
2d370 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d380 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d390 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d3a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d3b0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
2d3c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2d3d0 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
2d3e0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
2d3f0 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
2d400 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20  .**.** {H15115} 
2d410 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2d420 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
2d430 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d450 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d460 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d470 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
2d480 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
2d490 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2d4a0 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
2d4b0 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
2d4c0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2d4d0 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  H15118} The [sql
2d4e0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2d4f0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2d500 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2d510 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2d520 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d530 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2d540 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2d550 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2d560 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2d570 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
2d580 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2d590 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
2d5a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
2d5b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2d5c0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2d5d0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2d5e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d5f0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2d600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2d610 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
2d620 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2d630 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2d640 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2d650 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68  *.** {H15124} Th
2d660 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d670 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
2d680 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2d690 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2d6a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2d6b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2d6c0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2d6d0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2d6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2d6f0 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2d700 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
2d710 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2d720 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2d730 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2d740 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2d750 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
2d760 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2d770 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2d780 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2d790 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2d7a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d7b0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2d7c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2d7d0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2d7e0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2d7f0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
2d800 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2d810 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2d820 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2d830 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2d840 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
2d850 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d860 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
2d870 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2d880 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2d890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2d8a0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2d8b0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2d8c0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
2d8d0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
2d8e0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2d8f0 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
2d900 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2d910 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d920 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2d930 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20  ** {H15133} The 
2d940 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d950 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2d960 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2d970 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2d980 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2d990 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2d9a0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2d9b0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2d9c0 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2d9d0 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2d9e0 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2d9f0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2da00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2da10 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
2da20 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
2da30 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2da40 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
2da50 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
2da60 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2da70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2da80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2da90 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
2daa0 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
2dab0 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
2dac0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
2dad0 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
2dae0 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
2daf0 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
2db00 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
2db10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2db20 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
2db30 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
2db40 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2db50 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2db60 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
2db70 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
2db80 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2db90 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2dba0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2dbb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2dbc0 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
2dbd0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
2dbe0 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
2dbf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2dc00 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2dc10 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2dc20 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2dc30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2dc40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2dc50 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2dc60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2dc70 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2dc80 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2dc90 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2dca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2dcb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2dcc0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2dcd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2dce0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2dcf0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2dd00 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2dd10 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2dd20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2dd30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2dd40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2dd50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2dd60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2dd70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2dd80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2dd90 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2dda0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ddb0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2ddc0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2ddd0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2dde0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2ddf0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2de00 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2de10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2de20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2de30 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2de40 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2de50 74 20 7b 48 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a  t {H16210}.**.**
2de60 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
2de70 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65  ion of aggregate
2de80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
2de90 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2dea0 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61  to allocate.** a
2deb0 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73   structure for s
2dec0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2ded0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  te..**.** The fi
2dee0 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2def0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2df00 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65  ontext() routine
2df10 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2df20 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 61  .** particular a
2df30 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74 65  ggregate, SQLite
2df40 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74 65   allocates nByte
2df50 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  s of memory, zer
2df60 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20  oes out that.** 
2df70 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2df80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2df90 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61   it. On second a
2dfa0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2dfb0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2dfc0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2dfd0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2dfe0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2dff0 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20  ction index,.** 
2e000 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
2e010 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68 65  is returned. The
2e020 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e030 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
2e040 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20   can use.** the 
2e050 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72 20  returned buffer 
2e060 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61  to accumulate da
2e070 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ta..**.** SQLite
2e080 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2e090 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74  rees the allocat
2e0a0 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20 74  ed buffer when t
2e0b0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2e0c0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
2e0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2e0e0 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
2e0f0 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  d be a copy of t
2e100 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2e110 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2e120 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2e130 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2e140 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2e150 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f   the callback ro
2e160 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2e170 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2e180 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ate function..**
2e190 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2e1a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2e1b0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2e1c0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2e1d0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
2e1e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2e1f0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2e200 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e210 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66 69 72  {H16211} The fir
2e220 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  st invocation of
2e230 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2e240 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2e250 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ] for.**        
2e260 20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69    a particular i
2e270 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61 67  nstance of an ag
2e280 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2e290 20 28 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c   (for a particul
2e2a0 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ar.**          c
2e2b0 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73 65 73  ontext C) causes
2e2c0 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f 63   SQLite to alloc
2e2d0 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ate N bytes of m
2e2e0 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20 20  emory,.**       
2e2f0 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65 6d     zero that mem
2e300 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  ory, and return 
2e310 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2e320 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72   allocated memor
2e330 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 33  y..**.** {H16213
2e340 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  } If a memory al
2e350 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2e360 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20  ccurs during.** 
2e370 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e380 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2e390 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74  ext(C,N)] then t
2e3a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
2e3b0 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rns 0..**.** {H1
2e3c0 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64  6215} Second and
2e3d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2e3e0 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20  cations of.**   
2e3f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2e400 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2e410 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20  t(C,N)] for the 
2e420 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69  same context poi
2e430 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20  nter C.**       
2e440 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20     ignore the N 
2e450 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
2e460 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2e470 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  o the same.**   
2e480 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20         block of 
2e490 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
2e4a0 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76  by the first inv
2e4b0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  ocation..**.** {
2e4c0 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f  H16217} The memo
2e4d0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2e4e0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2e4f0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2e500 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2e510 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2e520 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  eed on the next 
2e530 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e540 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20  _reset()].**    
2e550 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2e560 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f  3_finalize()] fo
2e570 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2e580 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61  statement] conta
2e590 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
2e5a0 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20    the aggregate 
2e5b0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2e5c0 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ted with context
2e5d0 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
2e5e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e5f0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
2e600 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
2e610 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
2e620 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
2e630 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
2e640 48 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  H16240}.**.** Th
2e650 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2e660 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e670 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e680 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2e690 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2e6a0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2e6b0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2e6c0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2e6d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e6e0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2e6f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2e700 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2e710 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2e720 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2e730 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2e740 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e750 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2e760 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2e770 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2e780 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2e790 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2e7a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2e7b0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e7c0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2e7d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2e7e0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
2e7f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2e800 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2e810 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2e820 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2e830 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2e840 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2e850 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e860 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2e870 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2e880 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2e890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e8a0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2e8b0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2e8c0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2e8d0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2e8e0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2e8f0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2e900 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
2e910 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2e920 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2e930 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2e940 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2e950 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2e960 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
2e970 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
2e980 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e990 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2e9a0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2e9b0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2e9c0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2e9d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e9e0 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2e9f0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2ea00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ea10 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2ea20 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ea30 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2ea40 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2ea50 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2ea60 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2ea70 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ea80 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2ea90 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2eaa0 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73   {H16253} The [s
2eab0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2eac0 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74  b_handle(C)] int
2ead0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2eae0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2eaf0 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74           D point
2eb00 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2eb10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2eb20 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2eb30 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2eb40 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2eb50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2eb60 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2eb70 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2eb80 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2eb90 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2eba0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2ebb0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f  with [sqlite3_co
2ebc0 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c  ntext] C..*/.sql
2ebd0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
2ebe0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ebf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ec00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ec10 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
2ec20 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36  iliary Data {H16
2ec30 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  270}.**.** The f
2ec40 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
2ec50 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
2ec60 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
2ec70 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
2ec80 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
2ec90 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
2eca0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
2ecb0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
2ecc0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
2ecd0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
2ece0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
2ecf0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
2ed00 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
2ed10 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
2ed20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
2ed30 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
2ed40 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
2ed50 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
2ed60 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
2ed70 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
2ed80 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
2ed90 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
2eda0 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
2edb0 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
2edc0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
2edd0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2ede0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
2edf0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
2ee00 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
2ee10 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
2ee20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
2ee30 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
2ee40 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
2ee50 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
2ee60 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
2ee70 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
2ee80 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
2ee90 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2eea0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
2eeb0 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
2eec0 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
2eed0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2eee0 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
2eef0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
2ef00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ef10 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
2ef20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2ef30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ef40 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
2ef50 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
2ef60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ef70 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
2ef80 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
2ef90 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
2efa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2efb0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2efc0 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  n. If no metadat
2efd0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2efe0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2eff0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2f000 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2f010 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2f020 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2f030 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2f040 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2f050 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2f060 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2f070 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2f080 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2f090 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2f0a0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f0b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
2f0c0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
2f0d0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
2f0e0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
2f0f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
2f100 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
2f110 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
2f120 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
2f130 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f140 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
2f150 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2f160 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
2f170 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
2f180 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
2f190 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
2f1a0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
2f1b0 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20  ed..** If it is 
2f1c0 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
2f1d0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2f1e0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
2f1f0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
2f200 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2f210 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
2f220 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
2f230 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
2f240 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
2f250 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
2f260 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2f270 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
2f280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2f290 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
2f2a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
2f2b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
2f2c0 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
2f2d0 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
2f2e0 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
2f2f0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
2f300 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
2f310 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
2f320 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
2f330 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
2f340 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
2f350 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
2f360 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
2f370 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
2f380 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  * In practice, m
2f390 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
2f3a0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
2f3b0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
2f3c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
2f3d0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
2f3e0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
2f3f0 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
2f400 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
2f410 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62  s and SQL variab
2f420 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  les..**.** These
2f430 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2f440 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2f450 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2f460 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2f470 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2f480 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2f490 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2f4a0 48 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c  H16272} The [sql
2f4b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f4c0 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,N)] interface
2f4d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f4e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
2f4f0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2f500 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e  iated with the N
2f510 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
2f520 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f  .**          who
2f540 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c  se context is C,
2f550 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72   or NULL if ther
2f560 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61  e is no metadata
2f570 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20   associated.**  
2f580 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61          with tha
2f590 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
2f5a0 2a 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20  ** {H16274} The 
2f5b0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2f5c0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2f5d0 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73  nterface assigns
2f5e0 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20   a metadata.**  
2f5f0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2f600 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72  P to the Nth par
2f610 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2f620 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  L function with 
2f630 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a  context C..**.**
2f640 20 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65   {H16276} SQLite
2f650 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2f660 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
2f670 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  th a single argu
2f680 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
2f690 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65   which is the me
2f6a0 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50  tadata pointer P
2f6b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
2f6c0 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
2f6d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2f6e0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2f6f0 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73  when SQLite ceas
2f700 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20  es to hold.**   
2f710 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64         the metad
2f720 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ata..**.** {H162
2f730 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65  77} SQLite cease
2f740 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61  s to hold metada
2f750 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75  ta for an SQL fu
2f760 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2f770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
2f780 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
2f790 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68  hat parameter ch
2f7a0 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
2f7b0 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69  6278} When [sqli
2f7c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f7d0 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76  C,N,P,D)] is inv
2f7e0 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75  oked, the destru
2f7f0 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctor.**         
2f800 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61   is called for a
2f810 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74  ny prior metadat
2f820 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2f830 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2f840 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
2f850 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61  context C and pa
2f860 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a  rameter N..**.**
2f870 20 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65   {H16279} SQLite
2f880 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72   will call destr
2f890 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d  uctors for any m
2f8a0 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f  etadata it is ho
2f8b0 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  lding.**        
2f8c0 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61    in a particula
2f8d0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
2f8e0 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69  ement] S when ei
2f8f0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
2f900 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f910 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  S)] or [sqlite3_
2f920 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20  finalize(S)] is 
2f930 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  called..*/.void 
2f940 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2f950 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2f960 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
2f970 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
2f980 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2f990 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
2f9a0 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
2f9b0 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
2f9c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
2f9d0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
2f9e0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
2f9f0 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32  r Behavior {H102
2fa00 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  80}.**.** These 
2fa10 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
2fa20 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
2fa30 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
2fa40 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
2fa50 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
2fa60 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2fa70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
2fa80 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
2fa90 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2faa0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
2fab0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
2fac0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2fad0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
2fae0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
2faf0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
2fb00 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
2fb10 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
2fb20 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
2fb30 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2fb40 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
2fb50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
2fb60 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
2fb70 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
2fb80 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
2fb90 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
2fba0 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
2fbb0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
2fbc0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
2fbd0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
2fbe0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
2fbf0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
2fc00 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
2fc10 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
2fc20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
2fc30 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
2fc40 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
2fc50 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
2fc60 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
2fc70 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
2fc80 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
2fc90 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2fca0 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
2fcb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
2fcc0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
2fcd0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2fce0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
2fcf0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
2fd00 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
2fd10 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
2fd20 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6400}.**.** Thes
2fd30 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2fd40 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
2fd50 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2fd60 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
2fd70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
2fd80 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2fd90 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
2fda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fdb0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2fdc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fdd0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
2fde0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2fdf0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2fe00 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2fe10 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
2fe20 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
2fe30 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
2fe40 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
2fe50 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
2fe60 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
2fe70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
2fe80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2fe90 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
2fea0 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
2feb0 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2fec0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2fed0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2fee0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2fef0 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
2ff00 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2ff10 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2ff20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ff30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2ff40 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
2ff50 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
2ff60 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
2ff70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2ff80 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
2ff90 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
2ffa0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
2ffb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2ffc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ffd0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
2ffe0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
2fff0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
30000 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
30010 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30020 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
30030 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
30040 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
30050 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
30060 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
30070 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
30080 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
30090 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
300a0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
300b0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
300c0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
300d0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
300e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
300f0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
30100 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
30110 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
30120 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
30130 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
30140 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30150 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
30160 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30170 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
30180 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
30190 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
301a0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
301b0 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74  eption..** SQLit
301c0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
301d0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
301e0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
301f0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
30200 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
30210 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30220 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
30230 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
30240 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
30250 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
30260 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
30270 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
30280 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
30290 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
302a0 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e  -8. SQLite.** in
302b0 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72  terprets the str
302c0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
302d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
302e0 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  ) as UTF-16 in n
302f0 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72  ative.** byte or
30300 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69  der.  If the thi
30310 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
30320 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30330 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
30340 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30350 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
30360 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
30370 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
30380 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
30390 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
303a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
303b0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20  haracter..** If 
303c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
303d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
303e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
303f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
30400 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
30410 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
30420 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
30430 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
30440 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
30450 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
30460 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
30470 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
30480 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30490 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
304a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
304b0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
304c0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
304d0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
304e0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
304f0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
30500 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
30510 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
30520 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
30530 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
30540 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
30550 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
30560 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
30570 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30580 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
30590 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
305a0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
305b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
305c0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
305d0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
305e0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42  n a function.  B
305f0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
30600 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
30610 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41  SQLITE_ERROR.  A
30620 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30630 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
30640 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
30650 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30660 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
30670 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
30680 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
30690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
306a0 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
306b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
306c0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
306d0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
306e0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
306f0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
30700 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72   is to long to r
30710 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
30720 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30730 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
30740 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
30750 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
30760 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
30770 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
30780 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
30790 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
307a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
307b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
307c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
307d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
307e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
307f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30800 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
30810 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
30820 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
30830 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
30840 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30850 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
30860 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
30870 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
30880 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30890 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
308a0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
308b0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
308c0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
308d0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
308e0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
308f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30900 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
30910 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
30920 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
30930 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30940 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30950 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
30960 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30970 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
30980 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30990 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
309a0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
309b0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
309c0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
309d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
309e0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
309f0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
30a00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30a10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
30a20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
30a30 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
30a40 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
30a50 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
30a60 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
30a70 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
30a80 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
30a90 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
30aa0 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61  ly..** SQLite ta
30ab0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
30ac0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
30ad0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
30ae0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
30af0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
30b00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
30b10 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66  nterfaces..** If
30b20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
30b30 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
30b40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
30b50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
30b60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
30b70 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
30b80 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
30b90 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
30ba0 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
30bb0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
30bc0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  er..** If the 3r
30bd0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
30be0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30bf0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
30c00 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67  es.** is non-neg
30c10 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d  ative, then as m
30c20 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63  any bytes (not c
30c30 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68  haracters) of th
30c40 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65  e text.** pointe
30c50 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20  d to by the 2nd 
30c60 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61  parameter are ta
30c70 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69  ken as the appli
30c80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a  cation-defined.*
30c90 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c  * function resul
30ca0 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68  t..** If the 4th
30cb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
30cc0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30cd0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
30ce0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
30cf0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
30d00 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
30d10 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
30d20 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
30d30 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
30d40 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
30d50 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
30d60 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
30d70 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
30d80 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
30d90 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
30da0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
30db0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30dc0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a  * interfaces or.
30dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30de0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
30df0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
30e00 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
30e10 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
30e20 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
30e30 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
30e40 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
30e50 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
30e60 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
30e70 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  it or call a des
30e80 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20  tructor when it 
30e90 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
30ea0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
30eb0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
30ec0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
30ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30ee0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
30ef0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
30f00 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
30f10 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
30f20 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
30f30 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
30f40 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
30f50 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
30f60 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
30f70 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
30f80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
30f90 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
30fa0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
30fb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30fc0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
30fd0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
30fe0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
30ff0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31000 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
31010 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
31020 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31030 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
31040 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
31050 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
31060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
31070 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
31080 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
31090 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
310a0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
310b0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
310c0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
310d0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
310e0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
310f0 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
31100 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
31110 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31120 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
31130 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74  harm..** A [prot
31140 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31150 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
31160 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
31170 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
31180 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31190 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
311a0 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
311b0 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
311c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
311d0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
311e0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
311f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
31200 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31210 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
31220 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
31230 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
31240 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
31250 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
31260 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31270 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
31280 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
31290 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
312a0 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
312b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
312c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
312d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  NTS:.**.** {H164
312e0 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  03} The default 
312f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
31300 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69  m any SQL functi
31310 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  on is NULL..**.*
31320 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b  * {H16406} The [
31330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
31340 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  lob(C,V,N,D)] in
31350 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31370 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31380 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31390 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20   a BLOB that is 
313a0 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
313b0 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e      in length an
313c0 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70  d with content p
313d0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a  ointed to by V..
313e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54  **.** {H16409} T
313f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31400 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20  lt_double(C,V)] 
31410 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31420 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31430 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
31440 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31450 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  be the floating 
31460 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a  point value V..*
31470 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68  *.** {H16412} Th
31480 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31490 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20  t_error(C,V,N)] 
314a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
314b0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
314c0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
314d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
314e0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
314f0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
31500 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
31510 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61  ITE_ERROR] and a
31520 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73   UTF-8 error mes
31530 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d  sage copied from
31540 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20   V up to the.** 
31550 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a           first z
31560 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69  ero byte or unti
31570 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65  l N bytes are re
31580 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  ad if N is posit
31590 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
315a0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
315b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
315c0 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  C,V,N)] interfac
315d0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
315e0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
315f0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31600 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
31610 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
31620 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
31630 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
31640 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  R] and a UTF-16 
31650 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
31660 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  r error message.
31670 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  **          copi
31680 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
31690 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
316a0 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74  erminator or unt
316b0 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20  il N bytes.**   
316c0 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20         are read 
316d0 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
316e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d  ..**.** {H16418}
316f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31700 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
31710 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  g(C)] interface 
31720 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
31730 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
31740 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63  alue of the func
31750 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31760 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31770 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
31780 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f        [SQLITE_TO
31790 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70  OBIG] and an app
317a0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
317b0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
317c0 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16421} The [sqli
317d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
317e0 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72  _nomem(C)] inter
317f0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31800 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
31810 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
31820 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31830 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
31840 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
31850 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
31860 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e  TE_NOMEM] and an
31870 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
31880 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
31890 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b  * {H16424} The [
318a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
318b0 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20  rror_code(C,E)] 
318c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
318d0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
318e0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
318f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
31900 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
31910 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
31920 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20  ode E..**       
31930 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73     The error mes
31940 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63  sage text is unc
31950 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
31960 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16427} The [sqli
31970 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43  te3_result_int(C
31980 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
31990 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
319a0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
319b0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
319c0 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  C to be the 32-b
319d0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
319e0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33   V..**.** {H1643
319f0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
31a00 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56  result_int64(C,V
31a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
31a20 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
31a30 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
31a40 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
31a50 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
31a60 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
31a70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d  ..**.** {H16433}
31a80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31a90 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e  sult_null(C)] in
31aa0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31ab0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31ac0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31ad0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31ae0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
31af0 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  6436} The [sqlit
31b00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
31b10 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,V,N,D)] interfa
31b20 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
31b30 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
31b40 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
31b50 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
31b60 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
31b70 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f           V up to
31b80 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31b90 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
31ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31bb0 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
31bc0 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e  s of V if N is n
31bd0 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
31be0 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20  ** {H16439} The 
31bf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31c00 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
31c10 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31c20 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31c30 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31c40 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31c50 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e   be the UTF-16 n
31c60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
31c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
31c80 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
31c90 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
31ca0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
31cb0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
31cc0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
31cd0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
31ce0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
31cf0 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16442} The [sqli
31d00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31d10 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6be(C,V,N,D)] in
31d20 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31d30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31d40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31d50 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31d60 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d   the UTF-16 big-
31d70 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
31d80 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
31d90 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
31da0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
31db0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
31dc0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
31dd0 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20  es or V if N is 
31de0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
31df0 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65  .** {H16445} The
31e00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31e10 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
31e20 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  D)] interface ch
31e30 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
31e40 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
31e50 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
31e60 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31   to be the UTF-1
31e70 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
31e80 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
31e90 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
31ea0 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
31eb0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
31ec0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
31ed0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
31ee0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
31ef0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
31f00 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  6448} The [sqlit
31f10 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
31f20 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
31f30 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
31f40 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
31f50 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
31f60 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e   C to be the [un
31f70 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31f80 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20  3_value].**     
31f90 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a       object V..*
31fa0 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68  *.** {H16451} Th
31fb0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31fc0 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d  t_zeroblob(C,N)]
31fd0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31fe0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31ff0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32000 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32010 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c   be an N-byte BL
32020 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e  OB of all zeros.
32030 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20  .**.** {H16454} 
32040 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32050 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64  ult_error()] and
32060 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32070 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20  _error16()].**  
32080 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
32090 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  es make a copy o
320a0 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65  f their error me
320b0 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65  ssage strings be
320c0 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  fore.**         
320d0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
320e0 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68  * {H16457} If th
320f0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
32100 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
32110 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32120 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
32130 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32140 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
32150 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
32160 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
32170 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
32180 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
32190 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
321a0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
321b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
321c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
321d0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74  e(C,V,N,D)] is t
321e0 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c  he constant [SQL
321f0 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20  ITE_STATIC].**  
32200 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20          then no 
32210 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76  destructor is ev
32220 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  er called on the
32230 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53   pointer V and S
32240 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  QLite.**        
32250 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56    assumes that V
32260 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a   is immutable..*
32270 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66  *.** {H16460} If
32280 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
32290 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
322a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
322b0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
322c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
322d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
322e0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
322f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32300 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
32310 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32320 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32330 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
32340 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32350 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32360 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
32370 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a  s the constant.*
32380 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
32390 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68  TE_TRANSIENT] th
323a0 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  en the interface
323b0 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  s makes a copy o
323c0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
323d0 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61    content of V a
323e0 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63  nd retains the c
323f0 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  opy..**.** {H164
32400 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  63} If the D des
32410 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
32420 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
32430 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
32440 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
32450 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32460 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
32470 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32480 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
32490 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
324a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
324b0 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
324c0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
324d0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
324e0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
324f0 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c  ,D)] is some val
32500 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
32510 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f            the co
32520 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
32530 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c  STATIC] and [SQL
32540 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
32550 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
32560 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
32570 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
32580 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74  r D with V as it
32590 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a  s only argument.
325a0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
325b0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
325c0 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75   with the V valu
325d0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
325e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
325f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32600 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32610 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
32620 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
32630 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
32640 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32650 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
32660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32670 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
32680 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
32690 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
326a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
326b0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
326c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
326d0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
326e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
326f0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
32700 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
32710 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32720 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
32730 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32740 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32750 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
32760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32770 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
32780 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
32790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
327a0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
327b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
327c0 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
327d0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
327e0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
327f0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
32800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32820 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
32830 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32840 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
32850 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
32860 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32870 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
32880 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32890 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
328a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
328b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
328c0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
328d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
328e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
328f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
32900 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32910 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
32920 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32930 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
32940 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32950 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32960 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
32970 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
32980 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
32990 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
329a0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
329b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
329c0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
329d0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
329e0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
329f0 63 65 73 20 7b 48 31 36 36 30 30 7d 0a 2a 2a 0a  ces {H16600}.**.
32a00 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32a10 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
32a20 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
32a30 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
32a40 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
32a50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
32a60 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
32a70 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
32a80 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
32a90 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
32aa0 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
32ab0 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
32ac0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
32ad0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32ae0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
32af0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32b00 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
32b10 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
32b20 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
32b30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32b40 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
32b50 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
32b60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
32b70 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
32b80 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
32b90 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
32ba0 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
32bb0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
32bc0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
32bd0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
32be0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
32bf0 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
32c00 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
32c10 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
32c20 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
32c30 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
32c40 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
32c50 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
32c60 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
32c70 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
32c80 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
32c90 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
32ca0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
32cb0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
32cc0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
32cd0 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
32ce0 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
32cf0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
32d00 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
32d10 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
32d20 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
32d30 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
32d40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
32d50 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
32d60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
32d70 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
32d80 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
32d90 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
32da0 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
32db0 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
32dc0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
32dd0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
32de0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
32df0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
32e00 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
32e10 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
32e20 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
32e30 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
32e40 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
32e50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
32e60 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
32e70 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
32e80 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
32e90 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
32ea0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
32eb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
32ec0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
32ed0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
32ee0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32ef0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
32f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
32f10 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
32f20 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
32f30 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
32f40 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
32f50 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
32f60 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
32f70 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
32f80 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
32f90 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
32fa0 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
32fb0 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
32fc0 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
32fd0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32fe0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
32ff0 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
33000 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
33010 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
33020 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
33030 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
33040 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
33050 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
33060 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
33070 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
33080 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
33090 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
330a0 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
330b0 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
330c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
330d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
330e0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
330f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33100 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
33110 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
33120 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
33130 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
33140 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
33150 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
33160 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
33170 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
33180 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
33190 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
331a0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
331b0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
331c0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
331d0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
331e0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
331f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33200 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
33210 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
33220 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
33230 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
33240 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
33250 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
33260 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
33270 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
33280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33290 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
332a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
332b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
332c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
332d0 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
332e0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
332f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33300 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33310 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
33320 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
33330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
33340 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
33350 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
33360 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
33370 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
33380 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
33390 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
333a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
333b0 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
333c0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
333d0 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
333e0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34  E..**.** {H16604
333f0 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
33400 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
33410 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
33420 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
33430 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33440 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
33450 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
33460 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
33470 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
33480 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
33490 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
334a0 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
334b0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
334c0 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
334d0 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
334e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  rs..**.** {H1660
334f0 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
33500 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
33510 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33520 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
33530 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
33540 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
33550 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
33560 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
33570 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
33580 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
33590 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nd D..**.** {H16
335a0 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
335b0 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
335c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
335d0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
335e0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
335f0 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
33600 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
33610 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
33620 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
33630 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
33640 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
33650 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
33660 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20  *.** {H16612} A 
33670 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33680 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
33690 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
336a0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ded..**.** {H166
336b0 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
336c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
336d0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
336e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
336f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33700 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
33710 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
33720 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54  **.** {H16618} T
33730 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
33740 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33750 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
33760 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
33770 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
33780 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
33790 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
337a0 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
337b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
337c0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
337d0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
337e0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
337f0 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63  .** {H16621} A c
33800 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33810 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33820 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
33830 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
33840 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
33850 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
33860 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33870 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
33880 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
33890 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
338a0 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
338b0 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ctor..**.** {H16
338c0 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
338d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
338e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
338f0 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
33900 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
33910 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
33920 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
33930 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
33940 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
33950 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
33960 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33970 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
33980 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
33990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
339a0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
339b0 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
339c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20  .**.** {H16627} 
339d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
339e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
339f0 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
33a00 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
33a10 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
33a20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33a30 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
33a40 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
33a50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
33a60 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
33a70 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
33a80 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
33a90 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
33aa0 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
33ab0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
33ac0 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
33ad0 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
33ae0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
33af0 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
33b00 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
33b10 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
33b20 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
33b30 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
33b40 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
33b50 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
33b60 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
33b70 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
33b80 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
33b90 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
33ba0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
33bb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
33bc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
33bd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33be0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33bf0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33c00 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
33c10 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
33c20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
33c30 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33c40 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33c50 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
33c60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33c70 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
33c80 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
33c90 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
33ca0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
33cb0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
33cc0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
33cd0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
33ce0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
33cf0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
33d00 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
33d10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33d20 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
33d30 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
33d40 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
33d50 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
33d60 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
33d70 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
33d80 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
33d90 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
33da0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33db0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
33dc0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
33dd0 48 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 6f  H16700}.**.** To
33de0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
33df0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
33e00 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33e10 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
33e20 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
33e30 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
33e40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
33e50 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
33e60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
33e70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33e80 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
33e90 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
33ea0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
33eb0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
33ec0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
33ed0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
33ee0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
33ef0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
33f00 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
33f10 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
33f20 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
33f30 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
33f40 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
33f50 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
33f60 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
33f70 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
33f80 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
33f90 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
33fa0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
33fb0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
33fc0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
33fd0 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
33fe0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
33ff0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
34000 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
34010 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
34020 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
34030 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
34040 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
34050 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
34060 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
34070 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
34080 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
34090 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
340a0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
340b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
340c0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
340d0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
340e0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
340f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
34100 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34110 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
34120 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
34130 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
34140 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
34150 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
34160 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
34170 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
34180 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
34190 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
341a0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
341b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
341c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
341d0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
341e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
341f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
34200 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
34210 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
34220 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
34230 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
34240 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34250 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
34260 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34270 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
34280 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
34290 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
342a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
342b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32  S:.**.** {H16702
342c0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
342d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
342e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
342f0 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
34300 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
34310 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34320 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
34330 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
34340 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34350 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
34360 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
34370 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
34380 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
34390 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
343a0 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
343b0 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
343c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
343d0 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
343e0 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
343f0 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
34400 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68  ** {H16704} Each
34410 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
34420 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
34430 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
34440 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
34450 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34460 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
34470 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
34480 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
34490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
344a0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
344b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
344c0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
344d0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
344e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
344f0 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68  *.** {H16706} Th
34500 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
34510 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
34520 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
34530 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
34540 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
34550 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
34560 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
34570 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
34580 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
34590 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
345a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
345b0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
345c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
345d0 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
345e0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
345f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
34600 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
34610 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
34620 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34630 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
34640 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
34650 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
34660 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
34670 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
34680 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
34690 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
346a0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
346b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
346c0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
346d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
346e0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
346f0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
34700 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
34710 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
34720 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
34730 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
34740 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
34750 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
34760 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
34770 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
34780 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
34790 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
347a0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
347b0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
347c0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
347d0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
347e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
347f0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34800 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34810 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34820 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
34830 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
34840 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
34850 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
34860 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
34870 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
34880 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
34890 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
348a0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
348b0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
348c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
348d0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
348e0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
348f0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
34900 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
34910 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
34920 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
34930 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
34940 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
34950 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
34960 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
34970 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
34980 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
349a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
349b0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
349c0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
349d0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
349e0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
349f0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
34a00 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
34a10 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
34a20 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
34a30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
34a40 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
34a50 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
34a60 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
34a70 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
34a80 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
34a90 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
34aa0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
34ab0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
34ac0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34ad0 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
34ae0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
34af0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
34b00 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
34b10 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
34b20 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
34b30 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
34b40 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
34b50 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
34b60 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
34b70 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
34b80 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
34b90 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
34ba0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
34bb0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
34bc0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
34bd0 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
34be0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
34bf0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
34c00 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
34c10 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
34c20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
34c30 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  bject..**.** INV
34c40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
34c50 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c  H10533} The [sql
34c60 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
34c70 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73  nterface invokes
34c80 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20   the xSleep.**  
34c90 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f          method o
34ca0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
34cb0 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20  qlite3_vfs|VFS] 
34cc0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20  in order to.**  
34cd0 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20          suspend 
34ce0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
34cf0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
34d00 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  for at least.** 
34d10 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69           M milli
34d20 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  seconds..**.** {
34d30 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c  H10536} The [sql
34d40 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
34d50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34d60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
34d70 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69  *          milli
34d80 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
34d90 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73   actually reques
34da0 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61  ted of the opera
34db0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
34dc0 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d   system, which m
34dd0 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
34de0 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65  han the paramete
34df0 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  r M..*/.int sqli
34e00 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
34e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34e20 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
34e30 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
34e40 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30  orary Files {H10
34e50 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  310}.**.** If th
34e60 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
34e70 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
34e80 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
34e90 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
34ea0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
34eb0 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
34ec0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
34ed0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
34ee0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
34ef0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
34f00 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
34f10 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
34f20 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
34f30 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
34f40 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
34f50 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
34f60 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
34f70 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
34f80 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
34f90 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
34fa0 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
34fb0 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
34fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34fd0 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
34fe0 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
34ff0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
35000 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35010 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35020 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35030 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
35040 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
35050 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
35060 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
35070 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
35080 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
35090 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
350a0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
350b0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
350c0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
350d0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
350e0 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74 61   See If The Data
350f0 62 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f 2d  base Is In Auto-
35100 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32  Commit Mode {H12
35110 39 33 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  930}.** KEYWORDS
35120 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
35130 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
35140 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35150 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
35160 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35170 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
35180 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
35190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
351a0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
351b0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
351c0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
351d0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
351e0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
351f0 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
35200 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
35210 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
35220 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
35230 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35240 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35250 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35260 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
35270 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
35280 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
35290 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
352a0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
352b0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
352c0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
352d0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
352e0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
352f0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
35300 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
35310 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35320 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35330 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35340 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35350 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
35360 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
35370 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
35380 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
35390 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
353a0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
353b0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
353c0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
353d0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
353e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
353f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35400 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54  **.** {H12931} T
35410 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
35420 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
35430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35440 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
35450 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
35460 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
35480 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
35490 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
354a0 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
354b0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
354c0 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
354d0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
354e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
354f0 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  H12933} Autocomm
35500 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
35510 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
35520 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
35530 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
35540 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
35550 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
35560 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
35570 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
35580 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
35590 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
355a0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
355b0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d  :.**.** {A12936}
355c0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
355d0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
355e0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
355f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
35610 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
35620 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
35630 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
35640 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35650 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
35660 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
35670 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35680 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
35690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
356a0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
356b0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
356c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
356d0 74 20 7b 48 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a  t {H13120}.**.**
356e0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
356f0 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
35700 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
35710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35720 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
35730 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
35740 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
35750 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 62  ongs.  The datab
35760 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72  ase handle retur
35770 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ned by.** sqlite
35780 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
35790 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
357a0 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73   handle that was
357b0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
357c0 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
357d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
357e0 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
357f0 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
35800 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
35810 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
35820 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
35830 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  t place..**.** I
35840 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
35850 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b 73   {H13123} The [s
35860 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35870 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
35880 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
358a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
358b0 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
358c0 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ated with the.**
358d0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
358e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
358f0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
35900 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
35910 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
35920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35930 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
35940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35950 74 20 7b 48 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {H13140}.**.**
35960 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
35970 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35980 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
35990 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
359a0 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
359b0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
359c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
359d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
359e0 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
359f0 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
35a00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35a10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35a20 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
35a30 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
35a40 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35a50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35a60 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
35a70 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
35a80 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
35a90 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
35aa0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
35ab0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
35ac0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
35ad0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
35ae0 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b  143} If D is a [
35af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35b00 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  ion] that holds 
35b10 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
35b20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69          unfinali
35b30 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  zed [prepared st
35b40 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
35b50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35b60 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
35b70 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  hen [sqlite3_nex
35b80 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
35b90 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
35ba0 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
35bb0 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20           to one 
35bc0 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
35bd0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
35be0 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a  iated with D..**
35bf0 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20  .** {H13146} If 
35c00 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
35c10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
35c20 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e  t holds no unfin
35c30 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20  alized.**       
35c40 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
35c50 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
35c60 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35c70 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
35c80 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
35c90 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
35ca0 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
35cb0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
35cc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d  ..**.** {H13149}
35cd0 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 65 70   If S is a [prep
35ce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35cf0 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
35d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
35d10 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53  *          and S
35d20 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74   is not the last
35d30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35d40 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a  ent in D, then.*
35d50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35d60 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
35d70 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
35d80 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
35d90 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
35da0 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  to the next prep
35db0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
35dc0 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a  n D after S..**.
35dd0 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53  ** {H13152} If S
35de0 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72   is the last [pr
35df0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35e00 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  ] in the.**     
35e10 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
35e20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65  onnection] D the
35e30 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  n the [sqlite3_n
35e40 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a  ext_stmt(D, S)].
35e50 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
35e60 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
35e70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35e80 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
35e90 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
35ea0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
35eb0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
35ec0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
35ed0 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
35ee0 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
35ef0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
35f00 63 6b 73 20 7b 48 31 32 39 35 30 7d 0a 2a 2a 0a  cks {H12950}.**.
35f10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
35f20 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
35f30 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
35f40 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
35f50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
35f60 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
35f70 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
35f80 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
35f90 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35fa0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35fb0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
35fc0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
35fd0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
35fe0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35ff0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
36000 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c   The sqlite3_rol
36010 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
36020 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36030 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
36040 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
36050 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
36060 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
36070 63 6f 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e  committed..** An
36080 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
36090 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
360a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
360b0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
360c0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
360d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
360e0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
360f0 20 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   The pArg argume
36100 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
36110 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
36120 62 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20  back..** If the 
36130 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
36140 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
36150 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
36160 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
36170 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
36180 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
36190 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  back..**.** If a
361a0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
361b0 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
361c0 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a  egistered, its.*
361d0 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  * pArg value is 
361e0 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
361f0 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
36200 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
36210 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
36220 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
36230 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
36240 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
36250 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
36260 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
36270 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
36280 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
36290 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
362a0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
362b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
362c0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
362d0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
362e0 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
362f0 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
36300 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65  to occur..** The
36310 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
36320 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
36330 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
36340 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
36350 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
36360 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
36370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36380 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
36390 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61   The rollback ca
363a0 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
363b0 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
363c0 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c  action is.** rol
363d0 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65  led back because
363e0 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61   a commit callba
363f0 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d  ck returned non-
36400 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20  zero..** <todo> 
36410 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f  Check on this </
36420 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  todo>.**.** INVA
36430 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36440 31 32 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  12951} The [sqli
36450 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36460 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
36470 65 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a  e registers the.
36480 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
36490 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20  back function F 
364a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
364b0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
364c0 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
364d0 20 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e     a transaction
364e0 20 63 6f 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20   commits on the 
364f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36500 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
36510 48 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c  H12952} The [sql
36520 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36530 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
36540 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
36550 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
36560 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
36570 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
36580 68 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  h the same [data
36590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
365a0 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
365b0 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
365c0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 61 20  irst call for a 
365d0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
365e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
365f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d  ..**.** {H12953}
36600 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
36610 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36620 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73  ok()] overwrites
36630 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
36640 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
36650 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61  ered by prior ca
36660 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  lls..**.** {H129
36670 35 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67  54} If the F arg
36680 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
36690 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
366a0 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
366b0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
366c0 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63  he commit hook c
366d0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
366e0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
366f0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
36700 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
36710 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
36720 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mmits..**.** {H1
36730 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f 6d  2955} If the com
36740 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
36750 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68  urns non-zero th
36760 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
36770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
36780 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
36790 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  llback..**.** {H
367a0 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12961} The [sqli
367b0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
367c0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
367d0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74 68  ace registers th
367e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  e.**          ca
367f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
36800 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
36810 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
36820 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
36830 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74 69       a transacti
36840 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e  on rolls back on
36850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
36870 0a 2a 2a 20 7b 48 31 32 39 36 32 7d 20 54 68 65  .** {H12962} The
36880 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
36890 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  ck_hook(D,F,P)] 
368a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
368b0 73 20 74 68 65 20 50 0a 2a 2a 20 20 20 20 20 20  s the P.**      
368c0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 66 72 6f      argument fro
368d0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
368e0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
368f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
36900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36910 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f  on] D, or NULL o
36920 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
36930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
36940 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
36950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36960 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  n D..**.** {H129
36970 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  63} Each call to
36980 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
36990 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  ck_hook()] overw
369a0 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
369b0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
369c0 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
369d0 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
369e0 7b 48 31 32 39 36 34 7d 20 49 66 20 74 68 65 20  {H12964} If the 
369f0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
36a00 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36a10 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
36a20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
36a30 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61   then the rollba
36a40 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  ck hook callback
36a50 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
36a60 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
36a70 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
36a80 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
36a90 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63  action rolls bac
36aa0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  k..*/.void *sqli
36ab0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36ac0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
36ad0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
36ae0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
36af0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
36b00 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
36b10 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
36b20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36b30 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
36b40 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
36b50 63 6b 73 20 7b 48 31 32 39 37 30 7d 0a 2a 2a 0a  cks {H12970}.**.
36b60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
36b70 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
36b80 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36b90 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
36ba0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
36bb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36bc0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
36bd0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
36be0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
36bf0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36c00 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
36c10 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
36c20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  deleted..** Any 
36c30 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
36c40 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
36c50 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
36c60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
36c70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36c80 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
36c90 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
36ca0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
36cb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
36cc0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
36cd0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
36ce0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
36cf0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
36d00 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ed..** The first
36d10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36d20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
36d30 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
36d40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
36d50 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36d60 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
36d70 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
36d80 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
36d90 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
36da0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
36db0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
36dc0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
36dd0 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
36de0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
36df0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
36e00 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
36e10 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
36e20 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
36e30 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
36e40 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
36e50 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
36e60 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
36e70 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
36e80 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
36e90 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
36ea0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
36eb0 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
36ec0 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
36ed0 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20  e case of.** an 
36ee0 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
36ef0 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
36f00 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
36f10 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
36f20 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
36f30 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
36f40 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
36f50 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
36f60 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
36f70 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
36f80 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
36f90 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
36fa0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
36fb0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
36fc0 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
36fd0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
36fe0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
36ff0 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
37000 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
37010 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
37020 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  971} The [sqlite
37030 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37040 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
37050 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
37060 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
37070 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
37080 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
37090 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
370a0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
370b0 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
370c0 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
370d0 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
370e0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
370f0 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37100 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
37110 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68  *.** {H12973} Th
37120 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
37130 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
37140 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37150 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
37160 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
37170 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
37180 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
37190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
371a0 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
371b0 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
371c0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
371d0 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66  *.** {H12975} If
371e0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
371f0 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
37200 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37210 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
37220 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
37230 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
37240 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
37250 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   made..**.** {H1
37260 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
37270 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
37280 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
37290 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
372a0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
372b0 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
372c0 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
372d0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
372e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
372f0 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20  ** {H12979} The 
37300 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
37310 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
37320 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
37330 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
37340 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
37350 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
37360 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
37370 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
37380 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38  ed..**.** {H1298
37390 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
373a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
373b0 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  pdate callback.*
373c0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
373d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
373e0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
373f0 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
37400 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
37410 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
37420 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
37430 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
37440 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
37450 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
37460 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  H12983} The thir
37470 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37480 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37490 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
374a0 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
374b0 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
374c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
374d0 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
374e0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
374f0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
37500 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
37510 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
37520 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38  ated...** {H1298
37530 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
37540 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
37550 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
37560 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
37570 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
37580 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
37590 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
375a0 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
375b0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
375c0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
375d0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
375e0 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
375f0 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
37600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37610 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
37620 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
37630 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
37640 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
37650 73 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73  shared cache} {s
37660 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
37670 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
37680 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
37690 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
376a0 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
376b0 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
376c0 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
376d0 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
376e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
376f0 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
37700 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
37710 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
37720 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
37730 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
37740 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
37750 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
37760 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
37770 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73  e..**.** Cache s
37780 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
37790 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66  d and disabled f
377a0 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f  or an entire pro
377b0 63 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54  cess. {END}.** T
377c0 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
377d0 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
377e0 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
377f0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
37800 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
37810 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
37820 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
37830 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
37840 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
37850 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
37860 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
37870 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
37880 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
37890 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
378a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
378b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
378c0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
378d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
378e0 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
378f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
37900 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
37910 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
37920 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
37930 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
37940 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a  ey were opened..
37950 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
37960 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
37970 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
37980 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73  d cache.  When s
37990 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
379a0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
379b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
379c0 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65  odule()] API use
379d0 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  d to register.**
379e0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
379f0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
37a00 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
37a10 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
37a20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
37a30 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
37a40 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
37a50 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
37a60 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
37a70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
37a80 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
37a90 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
37aa0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
37ab0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
37ac0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
37ad0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
37ae0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
37af0 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
37b00 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
37b10 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
37b20 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
37b30 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
37b40 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  citly..**.** INV
37b50 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
37b60 48 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73  H10331} A succes
37b70 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
37b80 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  of [sqlite3_enab
37b90 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
37ba0 42 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  B)].**          
37bb0 77 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64  will enable or d
37bc0 69 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61  isable shared ca
37bd0 63 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79  che mode for any
37be0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a   subsequently.**
37bf0 20 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65            create
37c00 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
37c10 65 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73  ection] in the s
37c20 61 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a  ame process..**.
37c30 2a 2a 20 7b 48 31 30 33 33 36 7d 20 57 68 65 6e  ** {H10336} When
37c40 20 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73   shared cache is
37c50 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
37c60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
37c70 64 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dule()].**      
37c80 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69      interface wi
37c90 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
37ca0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
37cb0 20 7b 48 31 30 33 33 37 7d 20 54 68 65 20 5b 73   {H10337} The [s
37cc0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
37cd0 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69  ared_cache(B)] i
37ce0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
37d00 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
37d10 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
37d20 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
37d30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a   successfully..*
37d40 2a 0a 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53 68  *.** {H10339} Sh
37d50 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
37d60 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
37d70 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
37d80 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
37d90 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
37da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
37db0 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
37dc0 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30  p Memory {H17340
37dd0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
37de0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37df0 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
37e00 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
37e10 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
37e20 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
37e30 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
37e40 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
37e50 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
37e60 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
37e70 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44  se library. {END
37e80 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74  }  Memory used t
37e90 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
37ea0 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70  .** pages to imp
37eb0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
37ec0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
37ed0 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  f non-essential 
37ee0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74  memory..** sqlit
37ef0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
37f00 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
37f10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
37f20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
37f30 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
37f40 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
37f50 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
37f60 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  equested..**.** 
37f70 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37f80 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65 20 5b  * {H17341} The [
37f90 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37fa0 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72  memory(N)] inter
37fb0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
37fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65  .**          fre
37fd0 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
37fe0 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
37ff0 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
38000 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  ential.**       
38010 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61     memory alloca
38020 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
38030 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
38040 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 34  ry..**.** {H1634
38050 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
38060 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
38070 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  )] returns the n
38080 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
38090 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61    of bytes actua
380a0 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68  lly freed, which
380b0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
380c0 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  r less.**       
380d0 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75     than the amou
380e0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
380f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
38100 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
38110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38120 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
38130 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20 7b  t On Heap Size {
38140 48 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  H17350}.**.** Th
38150 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  e sqlite3_soft_h
38160 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65  eap_limit() inte
38170 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22  rface places a "
38180 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f  soft" limit.** o
38190 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
381a0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
381b0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
381c0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
381d0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
381e0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
381f0 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
38200 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
38210 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
38220 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
38230 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
38240 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
38250 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
38260 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
38270 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
38280 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
38290 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rmed..**.** The 
382a0 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
382b0 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
382c0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
382d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
382e0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
382f0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
38300 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
38310 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
38320 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
38330 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
38340 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
38350 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
38360 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
38370 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  *.** A negative 
38380 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
38390 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74  r N means that t
383a0 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20  here is no soft 
383b0 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a  heap limit and.*
383c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * [sqlite3_relea
383d0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c  se_memory()] wil
383e0 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  l only be called
383f0 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20   when memory is 
38400 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68  exhausted..** Th
38410 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
38420 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
38430 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
38440 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
38450 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
38460 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
38470 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
38480 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
38490 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
384a0 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
384b0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
384c0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
384d0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
384e0 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73  ification.  This
384f0 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
38500 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
38510 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
38520 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
38530 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
38540 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
38550 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
38560 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
38570 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
38580 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
38590 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
385a0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
385b0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
385c0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
385d0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
385e0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
385f0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
38600 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
38610 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
38620 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
38630 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
38640 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
38650 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
38660 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
38670 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
38680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
38690 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
386a0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
386b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
386c0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
386d0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
386e0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
386f0 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
38700 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38710 2a 2a 0a 2a 2a 20 7b 48 31 36 33 35 31 7d 20 54  **.** {H16351} T
38720 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
38730 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
38740 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
38750 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a   a soft limit.**
38760 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62            of N b
38770 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75  ytes on the amou
38780 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
38790 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
387a0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
387b0 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74      using [sqlit
387c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
387d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
387e0 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  ()] at any point
387f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
38800 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  time..**.** {H16
38810 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  352} If a call t
38820 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
38830 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
38840 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c  _realloc()] woul
38850 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  d.**          ca
38860 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d  use the total am
38870 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65  ount of allocate
38880 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65  d memory to exce
38890 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
388a0 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d     soft heap lim
388b0 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  it, then [sqlite
388c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
388d0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
388e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e  *          in an
388f0 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
38900 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ce the memory us
38910 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f  age prior to pro
38920 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ceeding.**      
38930 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d      with the mem
38940 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
38950 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ttempt..**.** {H
38960 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20  16353} Calls to 
38970 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
38980 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
38990 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74  ealloc()] that t
389a0 72 69 67 67 65 72 0a 2a 2a 20 20 20 2