/ Hex Artifact Content
Login

Artifact 7c3746a124012efd3e93db4713f94fe225c7f3cd:


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 34 20 32 30 30 38 2f 30  n,v 1.374 2008/0
05f0: 37 2f 32 33 20 30 30 3a 35 32 3a 35 36 20 64 72  7/23 00:52:56 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 0a 2a 2a 0a 2a 2a 20 7b  NUMBER]..**.** {
1120: 48 31 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c  H10022} The [sql
1130: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74  ite3_version] st
1140: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73 68  ring constant sh
1150: 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20  all contain.**  
1160: 20 20 20 20 20 20 20 20 74 68 65 20 74 65 78 74          the text
1170: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
1180: 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e  VERSION] string.
1190: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 33 7d 20  .**.** {H10023} 
11a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  The [sqlite3_lib
11b0: 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63 74  version()] funct
11c0: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ion shall return
11d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
11e0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
11f0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20  qlite3_version] 
1200: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
1210: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
1220: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
1230: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
1240: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1250: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1260: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
1270: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1280: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
1290: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
12a0: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
12b0: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
12c0: 73 61 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53  safe {H10100} <S
12d0: 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  60100>.**.** SQL
12e0: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69  ite can be compi
12f0: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68  led with or with
1300: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68  out mutexes.  Wh
1310: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  en.** the [SQLIT
1320: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20  E_THREADSAFE] C 
1330: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1340: 72 6f 20 69 73 20 74 72 75 65 2c 20 6d 75 74 65  ro is true, mute
1350: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1360: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1370: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1380: 65 6e 20 74 68 61 74 20 6d 61 63 72 6f 20 69 73  en that macro is
1390: 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68 65 20 6d   false,.** the m
13a0: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
13b0: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
13c0: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
13d0: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
13e0: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
13f0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
1400: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
1410: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
1420: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
1430: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
1440: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1450: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1460: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1470: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1480: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1490: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
14a0: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
14b0: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
14c0: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
14d0: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
14e0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
14f0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1500: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1510: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1520: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1530: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
1540: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1550: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1560: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1570: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1580: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1590: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
15a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
15b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
15d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
15e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
15f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
1600: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
1610: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
1620: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
1630: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
1640: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1650: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1660: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1670: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1680: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1690: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
16a0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
16b0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
16c0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
16d0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
16e0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
16f0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1700: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1710: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1720: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1730: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1740: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1750: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1760: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1770: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1780: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1790: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
17a0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
17b0: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
17c0: 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
17d0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31  NTS:.**.** {H101
17e0: 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
17f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66  _threadsafe()] f
1800: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
1810: 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20 69 66 0a  turn nonzero if.
1820: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
1830: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1840: 77 69 74 68 20 74 68 65 20 69 74 73 20 6d 75 74  with the its mut
1850: 65 78 65 73 20 65 6e 61 62 6c 65 64 20 62 79 20  exes enabled by 
1860: 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
1870: 20 20 20 20 6f 72 20 7a 65 72 6f 20 69 66 20 53      or zero if S
1880: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1890: 65 64 20 73 75 63 68 20 74 68 61 74 20 6d 75 74  ed such that mut
18a0: 65 78 65 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  exes are.**     
18b0: 20 20 20 20 20 70 65 72 6d 61 6e 65 6e 74 6c 79       permanently
18c0: 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
18d0: 20 7b 48 31 30 31 30 32 7d 20 54 68 65 20 76 61   {H10102} The va
18e0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  the [sqlite3_thr
1900: 65 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74  eadsafe()] funct
1910: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
1920: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65  shall not change
1930: 20 77 68 65 6e 20 6d 75 74 65 78 20 73 65 74 74   when mutex sett
1940: 69 6e 67 20 61 72 65 20 6d 6f 64 69 66 69 65 64  ing are modified
1950: 20 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   at.**          
1960: 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68  runtime using th
1970: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
1980: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  g()] interface a
1990: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
19a0: 65 73 70 65 63 69 61 6c 6c 79 20 74 68 65 20 5b  especially the [
19b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
19c0: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  NGLETHREAD],.** 
19d0: 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
19f0: 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EAD], [SQLITE_CO
1a00: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d  NFIG_SERIALIZED]
1a10: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
1a20: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
1a30: 5f 4d 55 54 45 58 5d 20 76 65 72 62 73 2e 0a 2a  _MUTEX] verbs..*
1a40: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
1a50: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
1a60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a70: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1a80: 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 48 31 32  tion Handle {H12
1a90: 30 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a  000} <S40200>.**
1aa0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
1ab0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
1ac0: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1ad0: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
1ae0: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
1af0: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
1b00: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
1b10: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
1b20: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
1b30: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
1b40: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
1b50: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
1b60: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
1b70: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
1b80: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
1b90: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1ba0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1bb0: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
1bc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bd0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
1be0: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
1bf0: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
1c00: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20  _close()].** is 
1c10: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
1c20: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
1c30: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
1c40: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
1c50: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c60: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
1c70: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
1c80: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1c90: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1ca0: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
1cb0: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
1cc0: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
1cd0: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
1ce0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1cf0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
1d00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d10: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
1d20: 72 20 54 79 70 65 73 20 7b 48 31 30 32 30 30 7d  r Types {H10200}
1d30: 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20 4b 45 59   <S10110>.** KEY
1d40: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
1d50: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
1d60: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
1d70: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
1d80: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
1d90: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
1da0: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
1db0: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
1dc0: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
1dd0: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
1de0: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
1df0: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
1e00: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
1e10: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
1e20: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
1e30: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
1e40: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
1e50: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
1e60: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
1e70: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
1e80: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
1e90: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
1ea0: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1eb0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30  TS:.**.** {H1020
1ec0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69  1} The [sqlite_i
1ed0: 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74  nt64] and [sqlit
1ee0: 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 20 73  e3_int64] type s
1ef0: 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a 20  hall specify.** 
1f00: 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 69           a 64-bi
1f10: 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1f20: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 32 7d  ..**.** {H10202}
1f30: 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 75 69 6e   The [sqlite_uin
1f40: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1f50: 33 5f 75 69 6e 74 36 34 5d 20 74 79 70 65 20 73  3_uint64] type s
1f60: 68 61 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a 20  hall specify.** 
1f70: 20 20 20 20 20 20 20 20 20 61 20 36 34 2d 62 69           a 64-bi
1f80: 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
1f90: 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  er..*/.#ifdef SQ
1fa0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
1fb0: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
1fc0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
1fd0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1fe0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
1ff0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2000: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2010: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2020: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2030: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2040: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2050: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2060: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2070: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2080: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2090: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
20a0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
20b0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
20c0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
20d0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
20e0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
20f0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2100: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2110: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2120: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2130: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2140: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2150: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2160: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2170: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2180: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2190: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
21a0: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
21b0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
21c0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
21d0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
21e0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
21f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2200: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2210: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
2220: 7b 48 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30  {H12010} <S30100
2230: 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S40200>.**.** 
2240: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
2250: 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
2260: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
2270: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41   object..**.** A
2280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2290: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
22a0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
22b0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
22c0: 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e  tatements].** an
22d0: 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
22e0: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
22f0: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
2300: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
2310: 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  h.** the [sqlite
2320: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2330: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2340: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2350: 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  t..** The [sqlit
2360: 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20  e3_next_stmt()] 
2370: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2380: 20 75 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 20   used to locate 
2390: 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  all.** [prepared
23a0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73   statements] ass
23b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
23c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23d0: 69 6f 6e 5d 20 69 66 20 64 65 73 69 72 65 64 2e  ion] if desired.
23e0: 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63 6f 64 65  .** Typical code
23f0: 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65   might look like
2400: 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
2410: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2420: 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  * sqlite3_stmt *
2430: 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28  pStmt;.** while(
2440: 20 28 70 53 74 6d 74 20 3d 20 73 71 6c 69 74 65   (pStmt = sqlite
2450: 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c 20  3_next_stmt(db, 
2460: 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62  0))!=0 ){.** &nb
2470: 73 70 3b 20 20 20 73 71 6c 69 74 65 33 5f 66 69  sp;   sqlite3_fi
2480: 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a  nalize(pStmt);.*
2490: 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  * }.** </pre></b
24a0: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
24b0: 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   If [sqlite3_clo
24c0: 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  se()] is invoked
24d0: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
24e0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
24f0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2500: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2510: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
2520: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2530: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 31 7d 20  .**.** {H12011} 
2540: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2550: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2560: 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20 64 65  ose(C)] shall de
2570: 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20  stroy the.**    
2580: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
2590: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
25a0: 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ct C..**.** {H12
25b0: 30 31 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  012} A successfu
25c0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
25d0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61  e3_close(C)] sha
25e0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
25f0: 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30  _OK..**.** {H120
2600: 31 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  13} A successful
2610: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2620: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c  3_close(C)] shal
2630: 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c 0a 2a 2a  l release all.**
2640: 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
2650: 20 61 6e 64 20 73 79 73 74 65 6d 20 72 65 73 6f   and system reso
2660: 75 72 63 65 73 20 61 73 73 6f 63 69 61 74 65 64  urces associated
2670: 20 77 69 74 68 20 5b 64 61 74 61 62 61 73 65 20   with [database 
2680: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20  connection].**  
2690: 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a          C..**.**
26a0: 20 7b 48 31 32 30 31 34 7d 20 41 20 63 61 6c 6c   {H12014} A call
26b0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
26c0: 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b 64 61 74  se(C)] on a [dat
26d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26e0: 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  ] C that.**     
26f0: 20 20 20 20 20 68 61 73 20 6f 6e 65 20 6f 72 20       has one or 
2700: 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72 65 70 61  more open [prepa
2710: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2720: 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a  shall fail with.
2730: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b  **          an [
2740: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
2750: 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b  or code..**.** {
2760: 48 31 32 30 31 35 7d 20 41 20 63 61 6c 6c 20 74  H12015} A call t
2770: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2780: 28 43 29 5d 20 77 68 65 72 65 20 43 20 69 73 20  (C)] where C is 
2790: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
27a0: 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
27b0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
27c0: 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39  K..**.** {H12019
27d0: 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
27e0: 63 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76  close(C)] is inv
27f0: 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  oked on a [datab
2800: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2810: 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  C.**          th
2820: 61 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67  at has a pending
2830: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2840: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68  e transaction sh
2850: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
2860: 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a     rolled back..
2870: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
2880: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36  S:.**.** {A12016
2890: 7d 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  } The C paramete
28a0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
28b0: 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20  ose(C)] must be 
28c0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
28d0: 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
28e0: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
28f0: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
2900: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
2910: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
2920: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2930: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2940: 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2950: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2960: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2970: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2980: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2990: 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b  lose(sqlite3 *);
29a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ../*.** The type
29b0: 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20   for a callback 
29c0: 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69  function..** Thi
29d0: 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  s is legacy and 
29e0: 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20  deprecated.  It 
29f0: 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20  is included for 
2a00: 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f  historical.** co
2a10: 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20  mpatibility and 
2a20: 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65  is not documente
2a30: 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e  d..*/.typedef in
2a40: 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c  t (*sqlite3_call
2a50: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
2a60: 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b  char**, char**);
2a70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a80: 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79  : One-Step Query
2a90: 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72   Execution Inter
2aa0: 66 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53  face {H12100} <S
2ab0: 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10000>.**.** The
2ac0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2ad0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2ae0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
2af0: 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20   running one or 
2b00: 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74  more.** SQL stat
2b10: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68  ements without h
2b20: 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61  aving to write a
2b30: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
2b40: 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   The UTF-8 encod
2b50: 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2b60: 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20  ents are passed 
2b70: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
2b80: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2b90: 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a  lite3_exec()..**
2ba0: 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   The statements 
2bb0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e  are evaluated on
2bc0: 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65  e by one until e
2bd0: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
2be0: 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70  r.** an interrup
2bf0: 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  t is encountered
2c00: 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20  , or until they 
2c10: 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54  are all done.  T
2c20: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2c30: 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  .** is an option
2c40: 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74  al callback that
2c50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
2c60: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
2c70: 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65   any query.** re
2c80: 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62  sults produced b
2c90: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
2ca0: 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70  ents.  The 5th p
2cb0: 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77  arameter tells w
2cc0: 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65  here.** to write
2cd0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
2ce0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  ges..**.** The e
2cf0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73  rror message pas
2d00: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
2d10: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2d20: 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e  er is held.** in
2d30: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2d40: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2d50: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76  alloc()].  To av
2d60: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
2d70: 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e  k,.** the callin
2d80: 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  g application sh
2d90: 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74  ould call [sqlit
2da0: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e  e3_free()] on an
2db0: 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  y error.** messa
2dc0: 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  ge returned thro
2dd0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2de0: 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61  meter when it ha
2df0: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
2e00: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
2e10: 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ssage..**.** If 
2e20: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2e30: 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72  t in the 2nd par
2e40: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f  ameter is NULL o
2e50: 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
2e60: 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67  g.** or a string
2e70: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79   containing only
2e80: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20   whitespace and 
2e90: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
2ea0: 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  o SQL.** stateme
2eb0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2ec0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
2ed0: 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  se is not change
2ee0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2ef0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2f00: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
2f10: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
2f20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f30: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2f40: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2f50: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2f60: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
2f70: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
2f80: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
2f90: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
2fa0: 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  se that cannot b
2fb0: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
2fc0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2fd0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2fe0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2ff0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
3000: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
3010: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31  S:.**.** {H12101
3020: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
3030: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
3040: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3050: 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,A,E)].**       
3060: 20 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74     shall sequent
3070: 69 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61  ially evaluate a
3080: 6c 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  ll of the UTF-8 
3090: 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20  encoded,.**     
30a0: 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73       semicolon-s
30b0: 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
30c0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
30d0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
30e0: 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
30f0: 67 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63  g S within the c
3100: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
3110: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3120: 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
3130: 32 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70  2102} If the S p
3140: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3150: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3160: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68  A,E)] is NULL th
3170: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
3180: 68 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68  he actions of th
3190: 65 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  e interface shal
31a0: 6c 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73  l be the same as
31b0: 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
31c0: 20 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20      S parameter 
31d0: 77 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74  were an empty st
31e0: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ring..**.** {H12
31f0: 31 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20  104} The return 
3200: 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
3210: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
3220: 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  be [SQLITE_OK] i
3230: 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  f all.**        
3240: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
3250: 20 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c   run successfull
3260: 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74  y and to complet
3270: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ion..**.** {H121
3280: 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  05} The return v
3290: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
32a0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
32b0: 65 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  e an appropriate
32c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e  .**          non
32d0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
32e0: 65 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74  e] if any SQL st
32f0: 61 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a  atement fails..*
3300: 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66  *.** {H12107} If
3310: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
3320: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
3330: 74 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71  ts handed to [sq
3340: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
3350: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
3360: 20 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65   results and the
3370: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
3380: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3390: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
33a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
33b0: 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
33c0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33d0: 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  r shall be.**   
33e0: 20 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f         invoked o
33f0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
3400: 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a   of result..**.*
3410: 2a 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68  * {H12110} If th
3420: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
3430: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61  ns a non-zero va
3440: 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  lue then [sqlite
3450: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
3460: 20 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72        shall abor
3470: 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
3480: 65 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e  ent it is curren
3490: 74 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a  tly evaluating,.
34a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70  **          skip
34b0: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
34c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  SQL statements, 
34d0: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
34e0: 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
34f0: 20 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73   {H12113} The [s
3500: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3510: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73  outine shall pas
3520: 73 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65  s its 4th parame
3530: 74 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20  ter through.**  
3540: 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31          as the 1
3550: 73 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  st parameter of 
3560: 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
3570: 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65  .** {H12116} The
3580: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3590: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
35a0: 73 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61  set the 2nd para
35b0: 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20  meter of its.** 
35c0: 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
35d0: 6b 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62  k to be the numb
35e0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
35f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
3600: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3610: 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  result..**.** {H
3620: 31 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  12119} The [sqli
3630: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3640: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3650: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3660: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3670: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3680: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3690: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
36a0: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
36b0: 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73            values
36c0: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
36d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
36e0: 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61  result set row a
36f0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  s.**          ob
3700: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
3710: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3720: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3730: 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  22} The [sqlite3
3740: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3750: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34   shall set the 4
3760: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
3770: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3780: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3790: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
37a0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
37b0: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
37c0: 20 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20         names of 
37d0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61  result columns a
37e0: 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
37f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3800: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  name()]..**.** {
3810: 48 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33  H12125} If the 3
3820: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
3830: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3840: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a   is NULL then.**
3850: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3860: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3870: 20 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72   silently discar
3880: 64 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  d query results.
3890: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20  .**.** {H12131} 
38a0: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
38b0: 72 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67  rs while parsing
38c0: 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61   or evaluating a
38d0: 6e 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a  ny of the SQL.**
38e0: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
38f0: 65 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61  ents in the S pa
3900: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
3910: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3920: 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20  ,E)] and if.**  
3930: 20 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61          the E pa
3940: 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e  rameter is not N
3950: 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ULL, then [sqlit
3960: 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c  e3_exec()] shall
3970: 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20   store.**       
3980: 20 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72     in *E an appr
3990: 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
39a0: 73 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e  ssage written in
39b0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
39c0: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
39d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
39e0: 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loc()]..**.** {H
39f0: 31 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69  12134} The [sqli
3a00: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3a10: 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  ,E)] routine sha
3a20: 6c 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ll set the value
3a30: 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
3a40: 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20  *E to NULL if E 
3a50: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
3a60: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72  there are no err
3a70: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ors..**.** {H121
3a80: 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
3a90: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3aa0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
3ab0: 20 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20   set the [error 
3ac0: 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20  code].**        
3ad0: 20 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63    and message ac
3ae0: 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
3af0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3b00: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3b10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3b20: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3b30: 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
3b40: 2a 20 7b 48 31 32 31 33 38 7d 20 49 66 20 74 68  * {H12138} If th
3b50: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
3b60: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3b70: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
3b80: 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  LL or an.**     
3b90: 20 20 20 20 20 65 6d 70 74 79 20 73 74 72 69 6e       empty strin
3ba0: 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  g or contains no
3bb0: 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
3bc0: 20 77 68 69 74 65 73 70 61 63 65 2c 20 63 6f 6d   whitespace, com
3bd0: 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ments,.**       
3be0: 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d 69 63 6f     and/or semico
3bf0: 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65 73 75 6c  lons, then resul
3c00: 74 73 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ts of [sqlite3_e
3c10: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20  rrcode()],.**   
3c20: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3c30: 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b  errmsg()], and [
3c40: 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
3c50: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
3c60: 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f 20 69  shall reset to i
3c70: 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72 6f 72  ndicate no error
3c80: 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  s..**.** ASSUMPT
3c90: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
3ca0: 31 34 31 7d 20 54 68 65 20 66 69 72 73 74 20 70  141} The first p
3cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3cc0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d 75 73  ite3_exec()] mus
3cd0: 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20 61 6e  t be an valid an
3ce0: 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20  d open.**       
3cf0: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
3d00: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  nection]..**.** 
3d10: 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64 61 74  {A12142} The dat
3d20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3d30: 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f   must not be clo
3d40: 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20  sed while.**    
3d50: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d60: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  xec()] is runnin
3d70: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 33  g..**.** {A12143
3d80: 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  } The calling fu
3d90: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  nction should us
3da0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3db0: 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20  )] to free.**   
3dc0: 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72         the memor
3dd0: 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67 20 69  y that *errmsg i
3de0: 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
3df0: 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72 72 6f  at once the erro
3e00: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65  r.**          me
3e10: 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67  ssage is no long
3e20: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a  er needed..**.**
3e30: 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20 53 51   {A12145} The SQ
3e40: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3e50: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61   in the 2nd para
3e60: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3e70: 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20  3_exec()].**    
3e80: 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d 61 69        must remai
3e90: 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68 69 6c  n unchanged whil
3ea0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3eb0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  )] is running..*
3ec0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
3ed0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f00: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3f10: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
3f20: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
3f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f40: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
3f50: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
3f60: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
3f70: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3f80: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
3f90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3fa0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
3fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
3fe0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
3ff0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
4000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4020: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
4030: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
4040: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
4050: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4060: 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10}.** KEYWORDS:
4070: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
4080: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
4090: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
40a0: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
40b0: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
40c0: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
40d0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
40e0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
40f0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4100: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
4110: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
4120: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
4130: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
4140: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
4150: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
4160: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
4170: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
4180: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
4190: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
41a0: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
41b0: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
41c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
41d0: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
41e0: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
41f0: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
4200: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
4210: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
4220: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
4230: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
4240: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
4250: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4260: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4270: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4280: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4290: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
42a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
42b0: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
42c0: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
42d0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
42e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
42f0: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
4300: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
4310: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
4320: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
4330: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
4340: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
4350: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4360: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4370: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4380: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4390: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
43a0: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
43b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43c0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
43d0: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
43e0: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
43f0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
4400: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
4410: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
4420: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
4430: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4440: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
4450: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4460: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4470: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4480: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4490: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
44a0: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
44b0: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
44c0: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
44d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44e0: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
44f0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4500: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
4510: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
4520: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
4530: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
4540: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
4550: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
4560: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
4570: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4580: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4590: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
45a0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
45b0: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
45c0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
45d0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
45e0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
45f0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
4610: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4620: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
4630: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
4640: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4650: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4660: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4670: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4680: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4690: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
46a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
46b0: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
46c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46d0: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
46e0: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
46f0: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
4700: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
4710: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
4720: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
4730: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
4740: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
4750: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4760: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4770: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4780: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
47a0: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
47b0: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
47c0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
47d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
47e0: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
47f0: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
4800: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
4810: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
4820: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
4830: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
4840: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
4850: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4860: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4870: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4880: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4890: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
48a0: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
48b0: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
48c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
48d0: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
48e0: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
4900: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
4910: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
4920: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
4930: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4940: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4950: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4960: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4970: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4990: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
49a0: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
49b0: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
49c0: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
49d0: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
49e0: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
49f0: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4a00: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
4a10: 7b 48 31 30 32 32 30 7d 0a 2a 2a 20 4b 45 59 57  {H10220}.** KEYW
4a20: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4a30: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
4a40: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
4a50: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4a60: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4a70: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4a80: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4a90: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4aa0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4ab0: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4ac0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4ad0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4ae0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4af0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4b00: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4b10: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4b20: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
4b30: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
4b40: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
4b50: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4b60: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4b70: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4b80: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4b90: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4ba0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4bb0: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4bc0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4bd0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4be0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4bf0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4c00: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4c10: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4c20: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
4c30: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
4c40: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
4c50: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4c60: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4c70: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4c80: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4c90: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4ca0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4cb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4cc0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4cd0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4ce0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4cf0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4d00: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4d10: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4d20: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4d30: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4d40: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4d50: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4d60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4d70: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4d80: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4d90: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4da0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4db0: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4dc0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4dd0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4de0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4df0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4e00: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4e10: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4e20: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4e30: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4e40: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4e50: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  tly zero..**.** 
4e60: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
4e70: 2a 20 7b 48 31 30 32 32 33 7d 20 54 68 65 20 73  * {H10223} The s
4e80: 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72  ymbolic name for
4e90: 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73   an extended res
4ea0: 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63  ult code shall c
4eb0: 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
4ec0: 20 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72      a related pr
4ed0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4ee0: 65 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a  e as a prefix..*
4ef0: 2a 0a 2a 2a 20 7b 48 31 30 32 32 34 7d 20 50 72  *.** {H10224} Pr
4f00: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
4f10: 65 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f  e names shall co
4f20: 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22  ntain a single "
4f30: 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  _" character..**
4f40: 0a 2a 2a 20 7b 48 31 30 32 32 35 7d 20 45 78 74  .** {H10225} Ext
4f50: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f60: 65 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f  e names shall co
4f70: 6e 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72  ntain two or mor
4f80: 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73  e "_" characters
4f90: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d  ..**.** {H10226}
4fa0: 20 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c   The numeric val
4fb0: 75 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65  ue of an extende
4fc0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4fd0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a  all contain the.
4fe0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65  **          nume
4ff0: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73  ric value of its
5000: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70   corresponding p
5010: 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f  rimary result co
5020: 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  de in.**        
5030: 20 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e    its least sign
5040: 69 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a  ificant 8 bits..
5050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
50b0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
5190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51a0: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
51b0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51c0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
51d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51e0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
51f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5200: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
5210: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5220: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
5230: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5240: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5250: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5260: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
5270: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5280: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5290: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
52a0: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
52b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
52c0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
52d0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
52e0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
52f0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5300: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
5310: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
5320: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
5330: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5340: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
5360: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
5390: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
53a0: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
53b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53c0: 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a   (14<<8))../*.**
53d0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
53e0: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
53f0: 70 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33  perations {H1023
5400: 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32  0} <H11120> <H12
5410: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700>.**.** These
5420: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5430: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5440: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5450: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5460: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5470: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5480: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5490: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
54a0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
54b0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
54c0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5550: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5570: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5580: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
55b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
55e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5610: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5630: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5640: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
5650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5660: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5670: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
56a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
56b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56c0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
56d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
56e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56f0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5700: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5710: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5720: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5730: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5740: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5750: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5760: 65 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30  eristics {H10240
5770: 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a  } <H11120>.**.**
5780: 20 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61   The xDeviceCapa
5790: 62 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20  bilities method 
57a0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
57b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
57c0: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
57d0: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
57e0: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
57f0: 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  e these.** bit v
5800: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
5810: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
5820: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
5830: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
5840: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
5850: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
5860: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5870: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
5880: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
5890: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58a0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
58b0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
58c0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
58d0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
58e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
58f0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
5900: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
5910: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
5920: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
5930: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
5940: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
5950: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
5960: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
5970: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
5980: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
5990: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
59a0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
59b0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
59c0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
59d0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
59e0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
59f0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
5a00: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
5a10: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
5a20: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
5a30: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
5a40: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5a50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
5a60: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5a70: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
5a80: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
5a90: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
5aa0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
5ab0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
5ac0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ad0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
5ae0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5af0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
5b00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
5b10: 32 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  2       0x000000
5b20: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
5b40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b50: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
5b60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b80: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5b90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ba0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5bb0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5bc0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5bd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5be0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
5bf0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
5c00: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
5c10: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
5c20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
5c30: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30  K       0x000000
5c40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
5c50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
5c60: 4b 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31  K       0x000001
5c70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5c80: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5c90: 45 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32  END     0x000002
5ca0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5cb0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5cc0: 41 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34  AL      0x000004
5cd0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
5ce0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
5cf0: 20 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d   Levels {H10250}
5d00: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20   <H11120>.**.** 
5d10: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
5d20: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
5d30: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
5d40: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
5d50: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
5d60: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
5d70: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
5d80: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
5d90: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
5da0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
5db0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5dc0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
5dd0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
5de0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
5df0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
5e00: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
5e10: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
5e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5e30: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
5e40: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
5e50: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
5e60: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
5e70: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
5e80: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
5e90: 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31  s {H10260} <H111
5ea0: 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  20>.**.** When S
5eb0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
5ec0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
5ed0: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
5ee0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5ef0: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
5f00: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
5f10: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
5f20: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5f30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
5f40: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
5f50: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
5f60: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
5f70: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
5f80: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
5f90: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
5fa0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
5fb0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
5fc0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
5fd0: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
5fe0: 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51   flushed. The SQ
5ff0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6000: 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74   flag means.** t
6010: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6020: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20  nc() semantics. 
6030: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6040: 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a  FULL flag means.
6050: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6060: 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e  -X style fullsyn
6070: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6080: 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  nc()..*/.#define
6090: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
60a0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
60b0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
60c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
60d0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
60f0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
6100: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6110: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6120: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6130: 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c  andle {H11110} <
6140: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e  S20110>.**.** An
6150: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6160: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
6170: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
6180: 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65  n the OS.** inte
6190: 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e  rface layer.  In
61a0: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
61b0: 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61  rface implementa
61c0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
61d0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
61e0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
61f0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
6200: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
6210: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
6220: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
6230: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
6240: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
6250: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6260: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
6270: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
6280: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
6290: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
62a0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
62b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
62c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
62d0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
62e0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
62f0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
6300: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6310: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
6320: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
6330: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
6340: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6350: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
6360: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
6370: 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ods Object {H111
6380: 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  20} <S20110>.**.
6390: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
63a0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
63b0: 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20  ite3_vfs] xOpen 
63c0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
63d0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
63e0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
63f0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
6400: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
6410: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6420: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6430: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6440: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6450: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6460: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6470: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
6480: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
6490: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
64a0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
64b0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
64c0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
64d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
64e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ct..**.** The fl
64f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
6500: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
6510: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
6520: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
6530: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6540: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
6550: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
6560: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
6570: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
6580: 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73   is a Mac OS-X s
6590: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
65a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
65b0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
65c0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
65d0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
65e0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
65f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
6600: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
6610: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
6620: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
6630: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
6640: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
6650: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
6660: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
6670: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
6680: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
6690: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
66a0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
66b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
66c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
66d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
66e0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
66f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
6700: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
6710: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
6720: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
6730: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
6740: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
6750: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
6760: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
6770: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
6780: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
6790: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
67a0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
67b0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
67c0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
67d0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
67e0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
67f0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
6800: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
6810: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
6820: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
6830: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
6840: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
6850: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
6860: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
6870: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
6880: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
6890: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
68a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
68b0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
68c0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
68d0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
68e0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
68f0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
6900: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
6910: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
6920: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
6930: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
6940: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
6950: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
6960: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
6970: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
6980: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
6990: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
69a0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
69b0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
69c0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
69d0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
69e0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
69f0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
6a00: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
6a10: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
6a20: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
6a30: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
6a40: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
6a50: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
6a60: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
6a70: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
6a80: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
6a90: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
6aa0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
6ab0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
6ac0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
6ad0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
6ae0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
6af0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
6b00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
6b10: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
6b20: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
6b30: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
6b40: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
6b50: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
6b60: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
6b70: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
6b80: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
6b90: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
6ba0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
6bb0: 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a   conflicts..**.*
6bc0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
6bd0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
6be0: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
6bf0: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
6c00: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
6c10: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
6c20: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
6c30: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
6c40: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
6c50: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
6c60: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
6c70: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
6c80: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6c90: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6ca0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
6cb0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
6cc0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
6cd0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
6ce0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
6cf0: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
6d00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
6d10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6d20: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
6d30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6d40: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
6d50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d60: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
6d70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6d80: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6d90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6da0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
6db0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6dc0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
6dd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6de0: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
6df0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e00: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
6e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e20: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
6e30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6e40: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
6e50: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e60: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
6e70: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
6e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e90: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6ea0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6eb0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6ec0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6ed0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6ee0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
6ef0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
6f00: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
6f10: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
6f20: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6f30: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6f40: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6f50: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6f60: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6f70: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6fa0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6fb0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6fc0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
6fd0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
6fe0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
6ff0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7000: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7010: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7020: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7030: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7040: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7050: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7060: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7070: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7080: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7090: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
70a0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
70b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
70c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
70d0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
70e0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
70f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7100: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
7110: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
7120: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
7130: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7140: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
7150: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
7160: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7170: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7180: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7190: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
71a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
71b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
71c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
71d0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
71e0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
71f0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
7200: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
7210: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7220: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7230: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
7240: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7250: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
7260: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7270: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7280: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7290: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
72a0: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
72b0: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
72c0: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
72d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
72e0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
72f0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
7300: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7310: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
7320: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
7330: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7340: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
7350: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7360: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7370: 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69  e*);.  /* Additi
7380: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
7390: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
73a0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
73b0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
73c0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
73d0: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
73e0: 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38  s {H11310} <S308
73f0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
7400: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
7410: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
7420: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
7430: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
7440: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
7450: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
7460: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
7470: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
7480: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
7490: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
74a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
74b0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
74c0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
74d0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
74e0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
74f0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7500: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
7510: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
7520: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
7530: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
7540: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
7550: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7560: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
7570: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
7580: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
75a0: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
75b0: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
75c0: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
75d0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
75e0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
75f0: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
7600: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
7610: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
7620: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
7630: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
7640: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64  s defined..*/.#d
7650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
7660: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
7670: 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      1../*.** CAP
7680: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
7690: 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32  dle {H17110} <S2
76a0: 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0130>.**.** The 
76b0: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
76c0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
76d0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
76e0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
76f0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
7700: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
7710: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
7720: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
7730: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
7740: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
7750: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
7760: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
7770: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
7780: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
7790: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
77a0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
77b0: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
77c0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
77d0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
77e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
77f0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
7800: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
7810: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7820: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
7830: 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30  ct {H11140} <S20
7840: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  100>.**.** An in
7850: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
7860: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7870: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
7880: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
7890: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
78a0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
78b0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
78c0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
78d0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
78e0: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
78f0: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
7900: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
7910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
7920: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
7930: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
7940: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
7950: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
7960: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
7970: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
7980: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
7990: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
79a0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
79b0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
79c0: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
79d0: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
79e0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
79f0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
7a00: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
7a10: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
7a20: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
7a30: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
7a40: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
7a50: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
7a60: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
7a70: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
7a80: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
7a90: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
7aa0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
7ab0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
7ac0: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
7ad0: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
7ae0: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
7af0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
7b00: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
7b10: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
7b20: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
7b30: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
7b40: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
7b50: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
7b60: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
7b70: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
7b80: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
7b90: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
7ba0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
7bb0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
7bc0: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
7bd0: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
7be0: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
7bf0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
7c00: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
7c20: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
7c30: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
7c40: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
7c50: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
7c60: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
7c70: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
7c80: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
7c90: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
7ca0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
7cb0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
7cc0: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
7cd0: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
7ce0: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
7cf0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
7d00: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
7d10: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
7d20: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
7d30: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
7d40: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
7d50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
7d60: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
7d70: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
7d80: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
7d90: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
7da0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
7db0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
7dc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
7dd0: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
7de0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
7df0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
7e00: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
7e10: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
7e20: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
7e30: 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c  .** {H11141} SQL
7e40: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
7e50: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
7e60: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
7e70: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
7e80: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
7e90: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
7ea0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
7eb0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
7ec0: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
7ed0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
7ee0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
7ef0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
7f00: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
7f10: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
7f20: 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42  called. {END}  B
7f30: 65 63 61 73 75 65 20 6f 66 20 74 68 65 20 70 72  ecasue of the pr
7f40: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c  evious sentense,
7f50: 20 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65   .** the [sqlite
7f60: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
7f70: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
7f80: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
7f90: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
7fa0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
7fb0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
7fc0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
7fd0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
7fe0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70  parameter is xOp
7ff0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
8000: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
8010: 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69  ** must invite i
8020: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
8030: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
8040: 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68  le.  Whenever th
8050: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
8060: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
8070: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
8080: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
8090: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
80a0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
80b0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
80c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
80d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20  .**.** {H11142} 
80e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
80f0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
8100: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
8110: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
8120: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8130: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
8140: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
8150: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
8160: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
8170: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
8180: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
8190: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
81a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
81b0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
81c0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b  _OPEN_CREATE]. {
81d0: 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  END}.** If xOpen
81e0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
81f0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8200: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8210: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8220: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8230: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8240: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8250: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8260: 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 4c  .** {H11143} SQL
8270: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8280: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8290: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
82a0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
82b0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
82c0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
82d0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
82e0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
82f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8300: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8320: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8330: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8340: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8350: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8360: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8370: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8380: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8390: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
83a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
83c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
83d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  OURNAL].** </ul>
83e0: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
83f0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
8400: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
8410: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
8420: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
8430: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
8440: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
8450: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
8460: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
8470: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
8480: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
8490: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
84a0: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
84b0: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
84c0: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
84d0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
84e0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
84f0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
8500: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
8510: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
8520: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
8530: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
8540: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
8550: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
8560: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
8570: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
8580: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
8590: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
85a0: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
85b0: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
85c0: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
85d0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
85e0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
85f0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
8600: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
8610: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8620: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
8630: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
8640: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
8650: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
8660: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8670: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
8680: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8690: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
86a0: 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 68  *.** {H11145} Th
86b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
86c0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
86d0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
86e0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
86f0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
8700: 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31  s closed.  {H111
8710: 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  46} The [SQLITE_
8720: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8730: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
8740: 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74  et for TEMP  dat
8750: 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73  abases, journals
8760: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
8770: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  nals..**.** {H11
8780: 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  147} The [SQLITE
8790: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
87a0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
87b0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
87c0: 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63  pened.** for exc
87d0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20  lusive access.  
87e0: 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74  This flag is set
87f0: 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65   for all files e
8800: 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65  xcept.** for the
8810: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
8820: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  ile..**.** {H111
8830: 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f  48} At least szO
8840: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
8850: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
8860: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
8870: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
8890: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
88a0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
88b0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
88c0: 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65   {END}  The xOpe
88d0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
88e0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
88f0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
8900: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
8910: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a  ust fill it in..
8920: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54  **.** {H11149} T
8930: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8940: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
8950: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
8960: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8970: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8980: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8990: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
89a0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
89b0: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
89c0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
89d0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
89e0: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
89f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8a00: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
8a10: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
8a20: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45  ast readable. {E
8a30: 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61  ND}  The file ca
8a40: 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
8a50: 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  ory..**.** {H111
8a60: 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  50} SQLite will 
8a70: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
8a80: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
8a90: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
8aa0: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
8ab0: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
8ac0: 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 65  me. {H11151} The
8ad0: 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
8ae0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
8af0: 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
8b00: 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
8b10: 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
8b20: 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68  ds. {END}  If th
8b30: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
8b40: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
8b50: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
8b60: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
8b70: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
8b80: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
8b90: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
8ba0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
8bb0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
8bc0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
8bd0: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
8be0: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
8bf0: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
8c00: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
8c10: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
8c20: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
8c30: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
8c40: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
8c50: 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  me() interfaces.
8c60: 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  ** are not stric
8c70: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
8c80: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
8c90: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
8ca0: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
8cb0: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
8cc0: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
8cd0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
8ce0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
8cf0: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
8d00: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
8d10: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
8d20: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
8d30: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
8d40: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
8d50: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
8d60: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
8d70: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
8d80: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
8d90: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
8da0: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
8db0: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
8dc0: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
8dd0: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
8de0: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65  onds given.  The
8df0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
8e00: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
8e10: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
8e20: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
8e30: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
8e40: 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ime..*/.typedef 
8e50: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
8e60: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
8e70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
8e80: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
8e90: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
8ea0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
8eb0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  sion number */. 
8ec0: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
8ed0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
8ee0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
8ef0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
8f00: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
8f10: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
8f20: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
8f30: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
8f40: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
8f50: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
8f60: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
8f70: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
8f80: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
8f90: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
8fa0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
8fb0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
8fc0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
8fd0: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
8fe0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
8ff0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
9000: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
9010: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9020: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
9030: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
9040: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
9050: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
9060: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
9070: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
9080: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9090: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
90a0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
90b0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
90c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
90d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
90e0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
90f0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
9100: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
9110: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9120: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
9130: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
9140: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
9150: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
9160: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
9170: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
9180: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
9190: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
91a0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
91b0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  sg);.  void *(*x
91c0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
91d0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
91e0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b   char *zSymbol);
91f0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
9200: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9210: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
9220: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
9230: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9240: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
9250: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
9260: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
9270: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
9280: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
9290: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
92a0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
92b0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
92c0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
92d0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
92e0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ar *);.  /* New 
92f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
9300: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
9310: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
9320: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
9330: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
9340: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
9350: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
9360: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9370: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
9380: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
9390: 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31  d {H11190} <H111
93a0: 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39  40>.**.** {H1119
93b0: 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  1} These integer
93c0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
93d0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
93e0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
93f0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9400: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9410: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9420: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
9430: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9440: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9450: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9460: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
9470: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31  ng for..** {H111
9480: 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  92} With SQLITE_
9490: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
94a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
94b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
94c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
94d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b  ile exists..** {
94e0: 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c  H11193} With SQL
94f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9500: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
9510: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9520: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9530: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
9540: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9550: 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57  e..** {H11194} W
9560: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9570: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
9580: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
9590: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
95a0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
95b0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
95c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
95d0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
95e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
95f0: 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e  ADWRITE 1.#defin
9600: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9610: 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a  READ      2../*.
9620: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
9630: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
9640: 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31  te Library {H101
9650: 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30  30} <S20000><S30
9660: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  100>.**.** The s
9670: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9680: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
9690: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
96a0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
96b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
96c0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
96d0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
96e0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
96f0: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
9700: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
9710: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  alize()..**.** A
9720: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
9730: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9740: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
9750: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
9760: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9770: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9780: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
9790: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
97a0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
97b0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
97c0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
97d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
97e0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
97f0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
9800: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
9810: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e  _shutdown().  On
9820: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
9830: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
9840: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9850: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
9860: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
9870: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
9880: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
9890: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
98a0: 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69  her things, sqli
98b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
98c0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a   shall invoke.**
98d0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
98e0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
98f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9900: 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f  ().** shall invo
9910: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
9920: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  d()..**.** The s
9930: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9940: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
9950: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e  rns SQLITE_OK on
9960: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20   success..** If 
9970: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
9980: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9990: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
99a0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
99b0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
99c0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
99d0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
99e0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
99f0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
9a00: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
9a10: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
9a20: 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49 54  other than SQLIT
9a30: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  E_OK..**.** The 
9a40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9a50: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
9a60: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
9a70: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
9a80: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
9a90: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
9aa0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
9ab0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
9ac0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
9ad0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9ae0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
9af0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
9b00: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
9b10: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
9b20: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
9b30: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
9b40: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
9b50: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
9b60: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
9b70: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
9b80: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
9b90: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
9ba0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
9bb0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
9bc0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9bd0: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ith the SQLITE_O
9be0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20  MIT_AUTOINIT.** 
9bf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
9c00: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
9c10: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
9c20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9c30: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
9c40: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
9c50: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
9c60: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
9c70: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
9c80: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
9c90: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9ca0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9cb0: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
9cc0: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
9cd0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
9ce0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
9cf0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
9d00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9d10: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
9d20: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
9d30: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
9d40: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
9d50: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
9d60: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
9d70: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
9d80: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
9d90: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
9da0: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
9db0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
9dc0: 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55  h SQLITE_OMIT_AU
9dd0: 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65 63  TOINIT might bec
9de0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
9df0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
9e00: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
9e10: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
9e20: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9e30: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
9e40: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
9e50: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
9e60: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
9e70: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
9e80: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9e90: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
9ea0: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
9eb0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
9ec0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9ed0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
9ee0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
9ef0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
9f00: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
9f10: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
9f20: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
9f30: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
9f40: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
9f50: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
9f60: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
9f70: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
9f80: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
9f90: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
9fa0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9fb0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
9fc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
9fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
9fe0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
9ff0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
a000: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a010: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
a020: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
a030: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
a040: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
a050: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
a060: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a070: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
a080: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
a090: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
a0a0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
a0b0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
a0c0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
a0d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
a0e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
a0f0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
a100: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
a110: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
a120: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
a130: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
a140: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
a150: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a160: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
a170: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
a180: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
a190: 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c  r unix, windows,
a1a0: 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65   or os/2..** Whe
a1b0: 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  n built for othe
a1c0: 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69  r platforms (usi
a1d0: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 53  ng the SQLITE_OS
a1e0: 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65  _OTHER=1 compile
a1f0: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
a200: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a210: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
a220: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
a230: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
a240: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a250: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
a260: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
a270: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
a280: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
a290: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
a2a0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
a2b0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
a2c0: 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  t return SQLITE_
a2d0: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  OK on success an
a2e0: 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
a2f0: 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
a300: 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
a310: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
a320: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
a330: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a340: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
a350: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
a360: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
a370: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
a380: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
a390: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
a3a0: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31  Lite Library {H1
a3b0: 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53  0145} <S20000><S
a3c0: 33 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30200>.**.** The
a3d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a3e0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
a3f0: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
a400: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
a410: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
a420: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
a430: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
a440: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
a450: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
a460: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
a470: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
a480: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
a490: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
a4a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
a4b0: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
a4c0: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
a4d0: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
a4e0: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
a4f0: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
a500: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
a510: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
a520: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a530: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
a540: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
a550: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
a560: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
a570: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
a580: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a590: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
a5a0: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
a5b0: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
a5c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a5d0: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
a5e0: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
a5f0: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
a600: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
a610: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
a620: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
a630: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
a640: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
a650: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
a660: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
a670: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e  hutdown()]..** N
a680: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
a690: 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  at sqlite3_confi
a6a0: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
a6b0: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
a6c0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a6d0: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
a6e0: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
a6f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
a700: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
a710: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
a720: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a730: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
a740: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a750: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
a760: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a770: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
a780: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
a790: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
a7a0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
a7b0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
a7c0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
a7d0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
a7e0: 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
a7f0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a800: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a810: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
a820: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
a830: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f  .**.** When a co
a840: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a850: 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
a860: 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
a870: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  rns SQLITE_OK..*
a880: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
a890: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
a8a0: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
a8b0: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
a8c0: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
a8d0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
a8e0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
a8f0: 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  code]..**.** The
a900: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a910: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  ) interface is c
a920: 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
a930: 6d 65 6e 74 61 6c 20 69 6e 20 74 68 61 74 0a 2a  mental in that.*
a940: 2a 20 6e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * new configurat
a950: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
a960: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
a970: 72 65 20 72 65 6c 65 61 73 65 73 20 61 6e 64 20  re releases and 
a980: 65 78 69 73 74 69 6e 67 0a 2a 2a 20 63 6f 6e 66  existing.** conf
a990: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
a9a0: 73 20 6d 61 79 20 62 65 20 64 69 73 63 6f 6e 74  s may be discont
a9b0: 69 6e 75 65 64 20 6f 72 20 6d 6f 64 69 66 69 65  inued or modifie
a9c0: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
a9d0: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
a9e0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
a9f0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
aa00: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20  cation Routines 
aa10: 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30  {H10155} <S20120
aa20: 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  >.**.** An insta
aa30: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
aa40: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
aa50: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
aa60: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
aa70: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
aa80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
aa90: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
aaa0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
aab0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
aac0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
aad0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
aae0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
aaf0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
ab00: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
ab10: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
ab20: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
ab30: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
ab40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
ab50: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
ab60: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72  _MALLOC].  By cr
ab70: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
ab80: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ab90: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
aba0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
abb0: 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67  config()] during
abc0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
abd0: 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  an.** applicatio
abe0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
abf0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
ac00: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
ac10: 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20  ubsystem.** for 
ac20: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
ac30: 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
ac40: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
ac50: 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
ac60: 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
ac70: 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20  with a built-in 
ac80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ac90: 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66   that is.** perf
aca0: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
acb0: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
acc0: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
acd0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
ace0: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
acf0: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
ad00: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
ad10: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
ad20: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
ad30: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
ad40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
ad50: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
ad60: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
ad70: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
ad80: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
ad90: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
ada0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
adb0: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
adc0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
add0: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
ade0: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
adf0: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
ae00: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
ae10: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
ae20: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
ae30: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
ae40: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
ae50: 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20  xMalloc, xFree, 
ae60: 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74  and xRealloc met
ae70: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
ae80: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
ae90: 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64  c(), free(), and
aea0: 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74   realloc() funct
aeb0: 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74  ions from the st
aec0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a  andard library..
aed0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
aee0: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
aef0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
af00: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
af10: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
af20: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
af30: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
af40: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
af50: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
af60: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
af70: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
af80: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
af90: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
afa0: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
afb0: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
afc0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
afd0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
afe0: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
aff0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
b000: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
b010: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
b020: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
b030: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
b040: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
b050: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
b060: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
b070: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
b080: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
b090: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
b0a0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
b0b0: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
b0c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
b0d0: 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
b0e0: 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
b0f0: 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65  locator.  (For e
b100: 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
b110: 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
b120: 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
b130: 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
b140: 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
b150: 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
b160: 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
b170: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
b180: 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
b190: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
b1a0: 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
b1b0: 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
b1c0: 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
b1d0: 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
b1e0: 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
b1f0: 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
b200: 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
b210: 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
b220: 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f  nd xShutdown..*/
b230: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
b240: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b250: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
b260: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
b270: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b280: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
b290: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
b2a0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
b2b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
b2c0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
b2d0: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
b2e0: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
b2f0: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
b300: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
b310: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
b320: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
b330: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
b340: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
b350: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
b360: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
b370: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
b380: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
b390: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
b3a0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
b3b0: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
b3c0: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
b3d0: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
b3e0: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
b3f0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
b400: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
b410: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
b420: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
b430: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
b440: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
b450: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
b460: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
b470: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
b480: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
b490: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
b4a0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
b4b0: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
b4c0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
b4d0: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  uration Options 
b4e0: 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30  {H10160} <S20000
b4f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  >.**.** These co
b500: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
b510: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
b520: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
b530: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
b540: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
b550: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
b560: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
b570: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
b580: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
b590: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
b5a0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
b5b0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
b5c0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
b5d0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
b5e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b5f0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
b600: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
b610: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
b620: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
b630: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
b640: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b650: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
b660: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
b670: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
b680: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b690: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
b6a0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
b6b0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
b6c0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
b6d0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
b6e0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
b6f0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
b700: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
b710: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
b720: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b730: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
b740: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
b750: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
b760: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
b770: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
b780: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
b790: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
b7a0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
b7b0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
b7c0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
b7d0: 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a  e thread.</dd>.*
b7e0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b7f0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
b800: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
b810: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
b820: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
b830: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
b840: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  on disables.** m
b850: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
b860: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
b870: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
b880: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
b890: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
b8a0: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
b8b0: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
b8c0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
b8d0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
b8e0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
b8f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
b900: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
b910: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
b920: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
b930: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
b940: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
b950: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
b960: 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64  environment.</dd
b970: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b980: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
b990: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
b9a0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
b9b0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
b9c0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
b9d0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
b9e0: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
b9f0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
ba00: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
ba10: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
ba20: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
ba30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
ba40: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
ba50: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
ba60: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
ba70: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
ba80: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
ba90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
baa0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
bab0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
bac0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
bad0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
bae0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
baf0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
bb00: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
bb10: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
bb20: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
bb30: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
bb40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bb50: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
bb60: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
bb70: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
bb80: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
bb90: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
bba0: 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20  ..**.** <p>This 
bbb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bbc0: 74 69 6f 6e 20 6d 65 72 65 6c 79 20 73 65 74 73  tion merely sets
bbd0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
bbe0: 65 78 20 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20  ex .** behavior 
bbf0: 74 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  to serialize acc
bc00: 65 73 73 20 74 6f 20 5b 64 61 74 61 62 61 73 65  ess to [database
bc10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20   connections].  
bc20: 49 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64  Individual.** [d
bc30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bc40: 6f 6e 73 5d 20 63 61 6e 20 6f 76 65 72 72 69 64  ons] can overrid
bc50: 65 20 74 68 69 73 20 73 65 74 74 69 6e 67 0a 2a  e this setting.*
bc60: 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  * using the [SQL
bc70: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
bc80: 5d 20 66 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74  ] flag to [sqlit
bc90: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f  e3_open_v2()].</
bca0: 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  p></dd>.**.** <d
bcb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
bcc0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
bcd0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
bce0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
bcf0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
bd00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
bd10: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
bd20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
bd30: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
bd40: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
bd50: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
bd60: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
bd70: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
bd80: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
bd90: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
bda0: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
bdb0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bdc0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
bdd0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
bde0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bdf0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
be00: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
be10: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
be20: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
be30: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
be40: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
be50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
be60: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
be70: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
be80: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
be90: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
bea0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
beb0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
bec0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
bed0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
bee0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
bef0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
bf00: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
bf10: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
bf20: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
bf30: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
bf40: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
bf50: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
bf60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
bf70: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
bf80: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
bf90: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
bfa0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bfb0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
bfc0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
bfd0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
bfe0: 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61 6e 20   single boolean 
bff0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 65  argument which e
c000: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
c010: 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 65 63  es.** the collec
c020: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
c030: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
c040: 74 69 63 73 2e 20 20 57 68 65 6e 20 64 69 73 61  tics.  When disa
c050: 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c  bled, the.** fol
c060: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
c070: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
c080: 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
c090: 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
c0a0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
c0b0: 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
c0c0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
c0d0: 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
c0e0: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
c0f0: 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
c100: 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c  _limit()].**   <
c110: 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  li> sqlite3_memo
c120: 72 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a 20 20  ry_status().**  
c130: 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a   </ul>.** </dd>.
c140: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c150: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
c160: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c170: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
c180: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
c190: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
c1a0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
c1b0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
c1c0: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
c1d0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
c1e0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
c1f0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a  e memory, the.**
c200: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
c210: 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a  ratch buffer (sz
c220: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
c230: 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29  r of buffers (N)
c240: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
c250: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
c260: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
c270: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
c280: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
c290: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
c2a0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
c2b0: 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f  (sz+4)*N bytes o
c2c0: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
c2d0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
c2e0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
c2f0: 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20  ratch buffer at 
c300: 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c  once per thread,
c310: 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   so.** N should 
c320: 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78  be set to the ex
c330: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
c340: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
c350: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72  .  The sz.** par
c360: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
c370: 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a   6 times the siz
c380: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
c390: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
c3a0: 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20  ize..** Scratch 
c3b0: 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64  buffers are used
c3c0: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
c3d0: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70  btree balance op
c3e0: 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20  eration.  If.** 
c3f0: 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  The btree balanc
c400: 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  er needs additio
c410: 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  nal memory beyon
c420: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
c430: 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68  ed by.** scratch
c440: 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e   buffers or if n
c450: 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
c460: 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66   space is specif
c470: 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ied, then SQLite
c480: 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  .** goes to [sql
c490: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74  ite3_malloc()] t
c4a0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
c4b0: 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64  ory it needs.</d
c4c0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c4d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
c4e0: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
c4f0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c500: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c510: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c520: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c530: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
c540: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
c550: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
c560: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
c570: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c580: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
c590: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
c5a0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
c5b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
c5c0: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
c5d0: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73   sz argument mus
c5e0: 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20  t be a power of 
c5f0: 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
c600: 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20  and 32768.  The 
c610: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
c620: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
c630: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
c640: 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a 2b  of at least (sz+
c650: 34 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  4)*N bytes of me
c660: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
c670: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
c680: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
c690: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
c6a0: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
c6b0: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
c6c0: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
c6d0: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
c6e0: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
c6f0: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
c700: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
c710: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
c720: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
c730: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
c740: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
c750: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
c760: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
c770: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
c780: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
c790: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c7a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
c7b0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AP</dt>.** <dd>T
c7c0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
c7d0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
c7e0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
c7f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
c800: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
c810: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
c820: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
c830: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
c840: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
c850: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
c860: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
c870: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
c880: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
c890: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
c8a0: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
c8b0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
c8c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
c8d0: 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  * bytes in the m
c8e0: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
c8f0: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
c900: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20  location size.  
c910: 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  If.** the first 
c920: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
c930: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
c940: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
c950: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
c960: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
c970: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c980: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
c990: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
c9a0: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
c9b0: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
c9c0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
c9d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
c9e0: 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d  C].  If the.** m
c9f0: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
ca00: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
ca10: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
ca20: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
ca30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
ca40: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
ca50: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
ca60: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
ca70: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
ca80: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
ca90: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
caa0: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
cab0: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64  cation needs.</d
cac0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cad0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
cae0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
caf0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
cb00: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
cb10: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
cb20: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
cb30: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
cb40: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
cb50: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
cb60: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
cb70: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
cb80: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
cb90: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
cba0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
cbb0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
cbc0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
cbd0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
cbe0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
cbf0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
cc00: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  EX</dt>.** <dd>T
cc10: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
cc20: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
cc30: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
cc40: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
cc50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
cc60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
cc70: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
cc80: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
cc90: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
cca0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
ccb0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
ccc0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
ccd0: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
cce0: 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  es..** This opti
ccf0: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
cd00: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
cd10: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
cd20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
cd30: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
cd40: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
cd50: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
cd60: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
cd70: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
cd80: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
cd90: 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a 23 64 65 66 69  e.</dd>.*/.#defi
cda0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
cdb0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
cdc0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
cdd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
cde0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
cdf0: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
ce00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ce10: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
ce20: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
ce30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
ce40: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
ce50: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
ce60: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
ce70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ce80: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
ce90: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
cea0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
ceb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cec0: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
ced0: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
cee0: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
cef0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
cf00: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
cf10: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
cf20: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
cf30: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
cf40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
cf50: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
cf60: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
cf70: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
cf80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
cf90: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
cfa0: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
cfb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
cfc0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
cfd0: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
cfe0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
cff0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
d000: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
d010: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
d020: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
d030: 74 68 6f 64 73 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  thods* */.../*.*
d040: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
d050: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
d060: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
d070: 64 65 73 20 7b 48 31 32 32 30 30 7d 0a 2a 2a 0a  des {H12200}.**.
d080: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
d090: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
d0a0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
d0b0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
d0c0: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
d0d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
d0e0: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
d0f0: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
d100: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
d110: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
d120: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
d130: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
d140: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
d150: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
d160: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
d170: 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  H12201} Each new
d180: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d190: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
d1a0: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
d1b0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
d1c0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
d1d0: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
d1e0: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
d1f0: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
d200: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
d210: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
d220: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
d230: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
d240: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
d250: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
d260: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
d270: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
d280: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
d290: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
d2a0: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
d2b0: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
d2c0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
d2d0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
d2e0: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
d2f0: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
d300: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
d310: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
d320: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30  {H12220} <S10700
d330: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  >.**.** Each ent
d340: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
d350: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
d360: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
d370: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
d380: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
d390: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
d3a0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
d3b0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
d3c0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
d3d0: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
d3e0: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
d3f0: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
d400: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
d410: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
d420: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
d430: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
d440: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
d450: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
d460: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
d470: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
d480: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
d490: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
d4a0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
d4b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
d4c0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
d4d0: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
d4e0: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
d4f0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
d500: 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
d510: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d520: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
d530: 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e   argument.  If n
d540: 6f 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  o successful INS
d550: 45 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  ERTs.** have eve
d560: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
d570: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
d580: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
d590: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
d5a0: 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63  If an INSERT occ
d5b0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
d5c0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
d5d0: 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65  owid of the inse
d5e0: 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72  rted.** row is r
d5f0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
d600: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
d610: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
d620: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
d630: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
d640: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
d650: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
d660: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
d670: 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20  e.** reverts to 
d680: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
d690: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
d6a0: 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64  he trigger fired
d6b0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52  ..**.** An INSER
d6c0: 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  T that fails due
d6d0: 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
d6e0: 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
d6f0: 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
d700: 6c 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65  l INSERT and doe
d710: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
d720: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d730: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
d740: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
d750: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
d760: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
d770: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
d780: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
d790: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
d7a0: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
d7b0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
d7c0: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
d7d0: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
d7e0: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
d7f0: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
d800: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
d810: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
d820: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
d830: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
d840: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
d850: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
d860: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
d870: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
d880: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
d890: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
d8a0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
d8b0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
d8c0: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
d8d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
d8e0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d8f0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
d900: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
d910: 2c 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63  , an INSERT is c
d920: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
d930: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
d940: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
d950: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
d960: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
d970: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
d980: 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  12221} The [sqli
d990: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d9a0: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
d9b0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f  n returns the ro
d9c0: 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  wid.**          
d9d0: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
d9e0: 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  nt successful IN
d9f0: 53 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f  SERT performed o
da00: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
da10: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
da20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
da30: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
da40: 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c   or higher level
da50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69  .**          tri
da60: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
da70: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
da80: 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c  ave been no qual
da90: 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a  ifying inserts..
daa0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54  **.** {H12223} T
dab0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
dac0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
dad0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
dae0: 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
daf0: 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65    same value whe
db00: 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
db10: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
db20: 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
db30: 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62     immediately b
db40: 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20  efore and after 
db50: 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a  a ROLLBACK..**.*
db60: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
db70: 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49 66  *.** {A12232} If
db80: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
db90: 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
dba0: 77 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20  w INSERT on the 
dbb0: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
dbc0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
dbd0: 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
dbe0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
dbf0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
dc00: 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
dc10: 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
dc20: 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
dc30: 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f  e last insert ro
dc40: 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  wid,.**         
dc50: 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
dc60: 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
dc70: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
dc80: 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
dc90: 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69           unpredi
dca0: 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
dcb0: 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
dcc0: 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
dcd0: 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
dce0: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
dcf0: 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  id..*/.sqlite3_i
dd00: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
dd10: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
dd20: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
dd30: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
dd40: 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
dd50: 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31  ows Modified {H1
dd60: 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a  2240} <S10600>.*
dd70: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
dd80: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
dd90: 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
dda0: 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
ddb0: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
ddc0: 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
ddd0: 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
dde0: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
ddf0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
de00: 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
de10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
de20: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
de30: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
de40: 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ..** Only change
de50: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
de60: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
de70: 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
de80: 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54  ATE,.** or DELET
de90: 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  E statement are 
dea0: 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
deb0: 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
dec0: 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
ded0: 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  s are not counte
dee0: 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
def0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
df00: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  s()] function.**
df10: 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74   to find the tot
df20: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  al number of cha
df30: 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63  nges including c
df40: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
df50: 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   triggers..**.**
df60: 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20   A "row change" 
df70: 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
df80: 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
df90: 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
dfa0: 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
dfb0: 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
dfc0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
dfd0: 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
dfe0: 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
dff0: 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
e000: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
e010: 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a  nt resolution,.*
e020: 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52  * rollback, ABOR
e030: 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52  T processing, DR
e040: 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20  OP TABLE, or by 
e050: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
e060: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
e070: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
e080: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
e090: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
e0a0: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
e0b0: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
e0c0: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
e0d0: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
e0e0: 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67  cript of a trigg
e0f0: 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74  er.  Most SQL st
e100: 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
e110: 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
e120: 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
e130: 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
e140: 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
e150: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
e160: 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
e170: 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
e180: 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
e190: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
e1a0: 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
e1b0: 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
e1c0: 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
e1d0: 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
e1e0: 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
e1f0: 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
e200: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61  ration..**.** Ca
e210: 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
e220: 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
e230: 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
e240: 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
e250: 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
e260: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
e270: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
e280: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
e290: 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
e2a0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
e2b0: 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
e2c0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
e2d0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
e2e0: 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
e2f0: 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
e300: 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
e310: 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c  * Thus, when cal
e320: 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
e330: 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
e340: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
e350: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
e360: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
e370: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
e380: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
e390: 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
e3a0: 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
e3b0: 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74   top level.  Wit
e3c0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
e3d0: 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
e3e0: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
e3f0: 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
e400: 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
e410: 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
e420: 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
e430: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
e440: 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
e450: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
e460: 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
e470: 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
e480: 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
e490: 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
e4a0: 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
e4b0: 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
e4c0: 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
e4d0: 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
e4e0: 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
e4f0: 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
e500: 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a   own context..**
e510: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
e520: 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e  ments the comman
e530: 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  d "DELETE FROM t
e540: 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20  able" without a 
e550: 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20  WHERE clause.** 
e560: 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20  by dropping and 
e570: 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74  recreating the t
e580: 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20  able.  (This is 
e590: 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e  much faster than
e5a0: 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67   going.** throug
e5b0: 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69  h and deleting i
e5c0: 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e  ndividual elemen
e5d0: 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c  ts from the tabl
e5e0: 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20  e.)  Because of 
e5f0: 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
e600: 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
e610: 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
e620: 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
e630: 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
e640: 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
e650: 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
e660: 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
e670: 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
e680: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
e690: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
e6a0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
e6b0: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
e6c0: 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
e6d0: 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
e6e0: 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
e6f0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
e700: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
e710: 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
e720: 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
e730: 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
e740: 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a  E 1" instead..**
e750: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
e760: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54  **.** {H12241} T
e770: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
e780: 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
e790: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65  shall return the
e7a0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
e7b0: 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67         row chang
e7c0: 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68 65  es caused by the
e7d0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
e7e0: 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20  ERT, UPDATE,.** 
e7f0: 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45           or DELE
e800: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  TE statement on 
e810: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
e820: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  e connection and
e830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
e840: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20  hin the same or 
e850: 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20 63  higher trigger c
e860: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
e870: 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a  if there have.**
e880: 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65            not be
e890: 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e  en any qualifyin
e8a0: 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a  g row changes..*
e8b0: 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74  *.** {H12243} St
e8c0: 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20  atements of the 
e8d0: 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f  form "DELETE FRO
e8e0: 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74  M tablename" wit
e8f0: 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  h no.**         
e900: 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68   WHERE clause sh
e910: 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65 71  all cause subseq
e920: 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
e930: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
e940: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f  e3_changes()] to
e950: 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65   return zero, re
e960: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a  gardless of the.
e970: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
e980: 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69  er of rows origi
e990: 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62  nally in the tab
e9a0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  le..**.** ASSUMP
e9b0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
e9c0: 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61 72  2252} If a separ
e9d0: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
e9e0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
e9f0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ea00: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ea10: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
ea20: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
ea30: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
ea40: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
ea50: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
ea60: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
ea70: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
ea80: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
ea90: 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
eaa0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
eab0: 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
eac0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
ead0: 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31  ied {H12260} <S1
eae0: 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
eaf0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
eb00: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
eb10: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
eb20: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a  ed by INSERT,.**
eb30: 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
eb40: 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  E statements sin
eb50: 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
eb60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
eb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20   opened..** The 
eb80: 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61  count includes a
eb90: 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20  ll changes from 
eba0: 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74  all trigger cont
ebb0: 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a  exts.  However,.
ebc0: 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
ebd0: 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
ebe0: 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
ebf0: 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20  plement REPLACE 
ec00: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
ec10: 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
ec20: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
ec30: 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20  , or DROP table 
ec40: 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54  processing..** T
ec50: 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  he changes are c
ec60: 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  ounted as soon a
ec70: 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
ec80: 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
ec90: 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  is.** completed 
eca0: 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
ecb0: 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61  ent handle is pa
ecc0: 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
ecd0: 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
ece0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
ecf0: 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  e()])..**.** SQL
ed00: 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
ed10: 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
ed20: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
ed30: 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
ed40: 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
ed50: 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
ed60: 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
ed70: 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61  (This is much fa
ed80: 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a  ster than going.
ed90: 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64  ** through and d
eda0: 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75  eleting individu
edb0: 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d  al elements from
edc0: 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65   the table.)  Be
edd0: 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a  cause of this.**
ede0: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74   optimization, t
edf0: 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20  he deletions in 
ee00: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
ee10: 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20  le" are not row 
ee20: 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77  changes and.** w
ee30: 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74  ill not be count
ee40: 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
ee50: 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b  3_changes() or [
ee60: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
ee70: 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63  anges()].** func
ee80: 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73  tions, regardles
ee90: 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  s of the number 
eea0: 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74  of elements that
eeb0: 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79   were originally
eec0: 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65  .** in the table
eed0: 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63  .  To get an acc
eee0: 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74  urate count of t
eef0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
ef00: 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a  s deleted, use.*
ef10: 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  * "DELETE FROM t
ef20: 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e  able WHERE 1" in
ef30: 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  stead..**.** See
ef40: 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
ef50: 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
ef60: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
ef70: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
ef80: 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {H12261} The [s
ef90: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
efa0: 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
efb0: 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
efc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
efd0: 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
efe0: 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
eff0: 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
f000: 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
f010: 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
f020: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
f030: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e   connection], in
f040: 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   any.**         
f050: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f060: 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  , since the data
f070: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
f080: 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a  was created..**.
f090: 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61 74  ** {H12263} Stat
f0a0: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
f0b0: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
f0c0: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
f0d0: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
f0e0: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
f0f0: 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  l not change the
f100: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
f110: 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
f120: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
f130: 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  anges()]..**.** 
f140: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
f150: 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20 61  ** {A12264} If a
f160: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
f170: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
f180: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
f190: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
f1a0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
f1b0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
f1c0: 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
f1d0: 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
f1e0: 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
f1f0: 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
f200: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
f210: 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
f220: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
f230: 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
f240: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
f250: 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
f260: 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
f270: 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20   Query {H12270} 
f280: 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30500>.**.** T
f290: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
f2a0: 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
f2b0: 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
f2c0: 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
f2d0: 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
f2e0: 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
f2f0: 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
f300: 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
f310: 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
f320: 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
f330: 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
f340: 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
f350: 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
f360: 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
f370: 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
f380: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
f390: 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
f3a0: 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
f3b0: 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
f3c0: 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
f3d0: 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
f3e0: 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
f3f0: 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
f400: 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
f410: 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
f420: 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
f430: 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
f440: 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
f450: 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
f460: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
f470: 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
f480: 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
f490: 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
f4a0: 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
f4b0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
f4c0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
f4d0: 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
f4e0: 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
f4f0: 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
f500: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
f510: 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
f520: 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
f530: 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
f540: 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
f550: 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
f560: 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
f570: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53  tion..**.** An S
f580: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
f590: 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
f5a0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
f5b0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
f5c0: 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72  .** If the inter
f5d0: 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
f5e0: 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
f5f0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
f600: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
f610: 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
f620: 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
f630: 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
f640: 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
f650: 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
f660: 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
f670: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
f680: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
f690: 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
f6a0: 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
f6b0: 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
f6c0: 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
f6d0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f6e0: 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
f6f0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
f700: 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54 68  *.** {H12271} Th
f710: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
f720: 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
f730: 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
f740: 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
f750: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
f760: 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
f770: 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
f780: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f790: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
f7a0: 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
f7b0: 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
f7c0: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
f7d0: 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
f7e0: 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c  {H12272} Any SQL
f7f0: 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
f800: 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62  is interrupted b
f810: 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  y [sqlite3_inter
f820: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
f830: 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
f840: 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
f850: 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  T]..**.** ASSUMP
f860: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
f870: 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74  2279} If the dat
f880: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f890: 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
f8a0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
f8b0: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
f8c0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
f8d0: 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
f8e0: 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
f8f0: 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
f900: 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
f910: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
f920: 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
f930: 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
f940: 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b  nt Is Complete {
f950: 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e  H10510} <S70200>
f960: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
f970: 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
f980: 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e   for command-lin
f990: 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
f9a0: 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
f9b0: 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
f9c0: 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
f9d0: 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53  orm complete a S
f9e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
f9f0: 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
fa00: 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
fa10: 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
fa20: 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
fa30: 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
fa40: 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ing.  These rout
fa50: 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65  ines return true
fa60: 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
fa70: 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
fa80: 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
fa90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
faa0: 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20   A statement is 
fab0: 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
fac0: 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
fad0: 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
fae0: 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
faf0: 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74  s not a fragment
fb00: 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20   of a.** CREATE 
fb10: 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
fb20: 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  t.  Semicolons t
fb30: 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
fb40: 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
fb50: 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
fb60: 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
fb70: 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
fb80: 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
fb90: 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
fba0: 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
fbb0: 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
fbc0: 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
fbd0: 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
fbe0: 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
fbf0: 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
fc00: 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
fc10: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
fc20: 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
fc30: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
fc40: 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
fc50: 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
fc60: 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
fc70: 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   SQL..**.** INVA
fc80: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
fc90: 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73 73  10511} A success
fca0: 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ful evaluation o
fcb0: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
fcc0: 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ete()] or.**    
fcd0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
fce0: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75 6e  omplete16()] fun
fcf0: 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20  ctions shall.** 
fd00: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
fd10: 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20 61  a numeric 1 if a
fd20: 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
fd30: 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61  ast non-whitespa
fd40: 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
fd50: 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
fd60: 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
fd70: 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69  on that is not i
fd80: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20  n between.**    
fd90: 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20        the BEGIN 
fda0: 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
fdb0: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
fdc0: 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
fdd0: 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72  0512} If a memor
fde0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
fdf0: 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
fe00: 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a   an invocation.*
fe10: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b 73  *          of [s
fe20: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
fe30: 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
fe40: 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68 65  omplete16()] the
fe50: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
fe60: 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20    routine shall 
fe70: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
fe80: 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  OMEM]..**.** ASS
fe90: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
fea0: 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70  {A10512} The inp
feb0: 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
fec0: 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
fed0: 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
fee0: 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
fef0: 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
ff00: 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68  *.** {A10513} Th
ff10: 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
ff20: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
ff30: 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
ff40: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
ff50: 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73          UTF-16 s
ff60: 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
ff70: 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
ff80: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
ff90: 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
ffa0: 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
ffb0: 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
ffc0: 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
ffd0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ffe0: 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
fff0: 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
10000 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
10010 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
10020 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
10030 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
10040 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
10050 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
10060 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
10070 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
10080 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
10090 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
100a0 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
100b0 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
100c0 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
100d0 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
100e0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
100f0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
10100 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
10110 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
10120 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
10130 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
10140 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
10150 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
10160 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
10170 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
10180 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
10190 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
101a0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
101b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
101c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
101d0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
101e0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
101f0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
10200 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
10210 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
10220 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
10230 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
10240 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
10250 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
10260 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
10270 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
10280 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
10290 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
102a0 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
102b0 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
102c0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
102d0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
102e0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
102f0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
10300 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
10310 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
10320 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
10330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10340 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
10350 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
10360 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
10370 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
10380 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
10390 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
103a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
103b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
103c0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
103d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
103e0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
103f0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
10400 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
10410 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10420 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
10430 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
10440 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
10450 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
10460 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
10470 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
10480 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
10490 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
104a0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
104b0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
104c0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
104d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
104e0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
104f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
10500 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
10510 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
10520 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
10530 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
10540 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
10550 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
10560 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
10570 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
10580 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
10590 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
105a0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
105b0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
105c0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
105d0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
105e0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
105f0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
10600 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
10610 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
10620 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
10630 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
10640 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
10650 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
10660 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
10670 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
10680 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
10690 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
106a0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
106b0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
106c0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
106d0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
106e0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
106f0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
10700 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
10710 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
10720 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
10730 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
10740 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
10750 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
10760 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
10770 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
10780 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
10790 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
107a0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
107b0 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
107c0 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
107d0 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
107e0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
107f0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
10800 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
10810 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
10820 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
10830 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
10840 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
10850 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
10860 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
10870 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
10880 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
10890 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
108a0 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
108b0 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
108c0 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
108d0 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
108e0 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
108f0 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
10900 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
10910 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
10920 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
10930 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
10940 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
10950 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
10960 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
10970 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
10980 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
10990 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
109a0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
109b0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
109c0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
109d0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
109e0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
109f0 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
10a00 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
10a10 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
10a20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
10a30 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
10a40 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
10a50 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
10a60 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
10a70 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
10a80 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
10a90 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
10aa0 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
10ab0 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
10ac0 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
10ad0 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
10ae0 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
10af0 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
10b00 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
10b10 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
10b20 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
10b30 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
10b40 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
10b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10b60 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
10b70 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
10b80 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
10b90 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
10ba0 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
10bb0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
10bc0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10bd0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
10be0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
10bf0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
10c00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
10c10 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68  *.** {H12311} Th
10c20 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
10c30 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20  handler(D,C,A)] 
10c40 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
10c50 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  eplace.**       
10c60 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b     busy callback
10c70 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
10c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
10c90 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20  with a new.**   
10ca0 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73         a new bus
10cb0 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20  y handler C and 
10cc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
10cd0 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a   pointer A..**.*
10ce0 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79  * {H12312} Newly
10cf0 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
10d00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
10d10 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73  shall have a bus
10d20 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  y.**          ha
10d30 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a  ndler of NULL..*
10d40 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68  *.** {H12314} Wh
10d50 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b  en two or more [
10d60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10d70 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a  ions] share a.**
10d80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
10d90 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
10da0 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20  _cache | common 
10db0 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20  cache],.**      
10dc0 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e      the busy han
10dd0 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  dler for the dat
10de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10df0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
10e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
10e10 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20   cache shall be 
10e20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
10e30 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72   cache encounter
10e40 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20  s a lock..**.** 
10e50 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75  {H12316} If a bu
10e60 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
10e70 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
10e80 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74  , then the SQLit
10e90 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  e interface.**  
10ea0 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f          that pro
10eb0 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e  voked the lockin
10ec0 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65  g event shall re
10ed0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
10ee0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  Y]..**.** {H1231
10ef0 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20  8} SQLite shall 
10f00 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79  invokes the busy
10f10 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77   handler with tw
10f20 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63  o arguments whic
10f30 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  h.**          ar
10f40 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
10f50 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64  pointer supplied
10f60 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
10f70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
10f80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75       [sqlite3_bu
10f90 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e  sy_handler()] an
10fa0 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  d a count of the
10fb0 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72   number of prior
10fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
10fd0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
10fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
10ff0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
11000 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41  g event..**.** A
11010 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11020 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73  * {A12319} A bus
11030 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
11040 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
11050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
11070 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11080 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
11090 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
110a0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
110b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
110c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
110d0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
110e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
110f0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
11100 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30   Timeout {H12340
11110 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
11120 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
11130 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
11140 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
11150 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
11160 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
11170 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
11180 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
11190 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
111a0 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a    The handler.**
111b0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
111c0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
111d0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
111e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
111f0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
11200 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31  accumulated. {H1
11210 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22  2343} After "ms"
11220 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
11230 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
11240 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
11250 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
11260 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
11270 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
11280 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
11290 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
112a0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
112b0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
112c0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
112d0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
112e0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
112f0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
11300 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
11310 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
11320 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
11330 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
11340 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
11350 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11360 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
11370 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
11380 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
11390 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
113a0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
113b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
113c0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
113d0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
113e0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
113f0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
11400 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
11410 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
11420 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68  *.** {H12341} Th
11430 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
11440 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
11450 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69  ion shall overri
11460 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20  de any prior.** 
11470 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
11480 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
11490 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75  ] or [sqlite3_bu
114a0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65  sy_handler()] se
114b0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tting.**        
114c0 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64    on the same [d
114d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
114e0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  on]..**.** {H123
114f0 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  43} If the 2nd p
11500 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11510 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11520 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61  t()] is less tha
11530 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
11540 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20   equal to zero, 
11550 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61  then the busy ha
11560 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63  ndler shall be c
11570 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a  leared so that.*
11580 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73  *          all s
11590 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e  ubsequent lockin
115a0 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61  g events immedia
115b0 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c  tely return [SQL
115c0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
115d0 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65   {H12344} If the
115e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
115f0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
11600 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20  timeout()] is a 
11610 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
11620 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74       number N, t
11630 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c  hen a busy handl
11640 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20  er shall be set 
11650 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
11660 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
11670 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
11680 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71  ethod in the [sq
11690 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20  lite3_vfs | VFS 
116a0 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c  interface] until
116b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74  .**          eit
116c0 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65  her the lock cle
116d0 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
116e0 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
116f0 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20  p time.**       
11700 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b     reported back
11710 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
11720 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
11730 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
11740 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11750 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
11760 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
11770 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
11780 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
11790 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48  nning Queries {H
117a0 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12370} <S10000>.
117b0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
117c0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
117d0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
117e0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
117f0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
11800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
11810 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
11820 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
11830 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
11840 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
11850 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
11860 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
11870 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
11880 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
11890 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
118a0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
118b0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
118c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
118d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
118e0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
118f0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
11900 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
11910 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
11920 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
11930 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
11940 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
11950 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
11960 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
11970 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
11980 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
11990 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
119a0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
119b0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
119c0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
119d0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
119e0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
119f0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
11a00 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
11a10 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
11a20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
11a30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
11a40 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
11a50 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
11a60 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
11a70 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
11a80 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
11a90 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
11aa0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
11ab0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
11ac0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
11ad0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
11ae0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
11af0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
11b00 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
11b10 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11b20 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
11b30 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
11b40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11b50 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
11b60 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
11b70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
11b80 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
11b90 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
11ba0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
11bb0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
11bc0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
11bd0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
11be0 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
11bf0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
11c00 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
11c10 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
11c20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
11c30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
11c40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
11c50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
11c60 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
11c70 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
11c80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
11c90 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
11ca0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
11cb0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
11cc0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
11cd0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
11ce0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
11cf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
11d00 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
11d10 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
11d20 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
11d30 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
11d40 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
11d50 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
11d60 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
11d70 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
11d80 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
11d90 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
11da0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
11db0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
11dc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
11dd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
11de0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
11df0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
11e00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11e10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
11e20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11e30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
11e40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
11e50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
11e60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
11e70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
11e80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
11e90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11ea0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
11eb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11ec0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
11ed0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11ee0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
11ef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
11f00 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11f10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
11f20 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
11f30 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
11f40 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
11f50 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
11f60 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
11f70 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
11f80 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
11f90 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
11fa0 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
11fb0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
11fc0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
11fd0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
11fe0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
11ff0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
12000 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
12010 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
12020 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
12030 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70  , it should.** p
12040 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
12050 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
12060 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
12070 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
12080 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
12090 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
120a0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
120b0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
120c0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
120d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
120e0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
120f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12100 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
12110 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12120 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
12130 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12140 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
12150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
12160 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
12170 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
12180 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
12190 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
121a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
121b0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
121c0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
121d0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
121e0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
121f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
12200 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
12210 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
12220 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
12230 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
12240 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
12250 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
12260 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
12270 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
12280 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
12290 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
122a0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
122b0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
122c0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
122d0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
122e0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
122f0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
12300 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
12310 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
12320 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
12330 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
12340 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
12350 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  msg()]..**.** IN
12360 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
12370 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73  {H12371} If a [s
12380 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12390 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f  ()] fails a memo
123a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ry allocation, t
123b0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
123c0 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68  it shall free th
123d0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75  e result table u
123e0 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f  nder constructio
123f0 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20  n, abort the.** 
12400 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
12410 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20  n process, skip 
12420 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
12430 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a  ueries, set the.
12440 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a  **          *paz
12450 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f  Result output po
12460 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
12470 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
12480 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
12490 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70  H12373} If the p
124a0 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  nColumn paramete
124b0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
124c0 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
124d0 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
124e0 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
124f0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
12500 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
12510 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
12520 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
12530 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
12540 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
12550 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
12560 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
12570 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e  y into *pnColumn
12580 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d  ..**.** {H12374}
12590 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61   If the pnRow pa
125a0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
125b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
125c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
125d0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
125e0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
125f0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
12600 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
12610 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12620 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62   writes the numb
12630 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68  er of rows in th
12640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
12650 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
12660 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f  query into *pnRo
12670 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36  w..**.** {H12376
12680 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
12690 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
126a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
126b0 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73  )] that computes
126c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72  .**          N r
126d0 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69  ows of result wi
126e0 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72  th C columns per
126f0 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20   row shall make 
12700 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20  *pazResult.**   
12710 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20         point to 
12720 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
12730 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20  ters to (N+1)*C 
12740 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68  strings where th
12750 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  e first.**      
12760 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72      C strings ar
12770 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  e column names a
12780 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  s obtained from.
12790 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
127a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
127b0 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74  ()] and the rest
127c0 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75   are column resu
127d0 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  lt values.**    
127e0 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
127f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
12800 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
12810 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20  ** {H12379} The 
12820 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61  values in the pa
12830 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65  zResult array re
12840 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
12850 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
12860 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
12870 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75  l remain valid u
12880 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20  ntil cleared by 
12890 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
128a0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ble()]..**.** {H
128b0 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65  12382} When an e
128c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
128d0 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ng evaluation of
128e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
128f0 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
12900 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20     the function 
12910 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65  shall set *pazRe
12920 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72  sult to NULL, wr
12930 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ite an error mes
12940 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
12950 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
12960 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
12970 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d  te3_malloc()], m
12980 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ake.**          
12990 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74  **pzErrmsg point
129a0 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d   to that error m
129b0 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75  essage, and retu
129c0 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rn a.**         
129d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
129e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
129f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
12a00 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
12a10 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
12a20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
12a30 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
12a40 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
12a50 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
12a60 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
12a70 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
12a80 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
12a90 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
12aa0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
12ab0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
12ac0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
12ad0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
12ae0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
12af0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
12b00 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
12b10 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
12b20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
12b30 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
12b40 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
12b50 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
12b60 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
12b70 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
12b80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
12b90 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
12ba0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
12bb0 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
12bc0 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
12bd0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12be0 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
12bf0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
12c00 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
12c10 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
12c20 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12c30 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
12c40 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
12c50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
12c60 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
12c70 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
12c80 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
12c90 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
12ca0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
12cb0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
12cc0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
12cd0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
12ce0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
12cf0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
12d00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
12d10 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
12d20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
12d30 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
12d40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
12d50 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
12d60 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
12d70 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
12d80 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
12d90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
12da0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
12db0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
12dc0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
12dd0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
12de0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
12df0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
12e00 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
12e10 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
12e20 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
12e30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
12e40 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
12e50 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
12e60 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
12e70 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
12e80 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
12e90 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
12ea0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
12eb0 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
12ec0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
12ed0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
12ee0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
12ef0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
12f00 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
12f10 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
12f20 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
12f30 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
12f40 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
12f50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
12f60 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
12f70 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
12f80 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
12f90 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
12fa0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
12fb0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
12fc0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
12fd0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
12fe0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
12ff0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
13000 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
13010 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
13020 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
13030 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
13040 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
13050 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
13060 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
13070 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
13080 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
13090 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
130a0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
130b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
130c0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
130d0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
130e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
130f0 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
13100 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
13110 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
13120 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
13130 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
13140 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
13150 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
13160 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
13170 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
13180 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
13190 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
131a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
131b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
131c0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
131d0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
131e0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
131f0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
13200 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
13210 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
13220 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
13230 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
13240 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
13250 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
13260 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
13270 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
13280 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
13290 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
132a0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
132b0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
132c0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
132d0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
132e0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
132f0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
13300 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
13310 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
13320 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
13330 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
13340 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
13350 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
13360 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
13370 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
13380 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
13390 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
133a0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
133b0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
133c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
133d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
133e0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
133f0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
13400 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
13410 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
13420 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13430 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13440 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
13450 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
13460 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13470 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
13480 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
13490 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
134a0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
134b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
134c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
134d0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
134e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
134f0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
13500 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
13510 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
13520 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
13530 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
13540 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
13550 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
13560 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13570 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
13580 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
13590 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
135a0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
135b0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
135c0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
135d0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
135e0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
135f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13600 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
13610 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
13620 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
13630 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
13640 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
13650 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
13660 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
13670 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
13680 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
13690 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
136a0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
136b0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
136c0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
136d0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
136e0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
136f0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
13700 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13710 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
13720 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
13730 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
13740 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
13750 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
13760 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
13770 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
13780 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
13790 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
137a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
137b0 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
137c0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
137d0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
137e0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
137f0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
13800 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
13810 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
13820 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
13830 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
13840 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
13850 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
13860 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
13870 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
13880 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
13890 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
138a0 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
138b0 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
138c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
138d0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
138e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
138f0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
13900 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
13910 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
13920 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
13930 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
13940 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
13950 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
13960 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
13970 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
13980 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
13990 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
139a0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
139b0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
139c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
139d0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
139e0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
139f0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
13a00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
13a10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
13a20 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
13a30 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
13a40 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
13a50 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
13a60 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
13a70 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
13a80 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
13a90 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
13aa0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
13ab0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
13ac0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
13ad0 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  g. {END}.**.** I
13ae0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
13af0 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b   {H17403}  The [
13b00 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13b10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
13b20 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  vmprintf()] inte
13b30 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20  rfaces.**       
13b40 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65      return eithe
13b50 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  r pointers to ze
13b60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
13b70 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64  F-8 strings held
13b80 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
13b90 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
13ba0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13bb0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c  alloc()] or NULL
13bc0 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20   pointers if.** 
13bd0 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c            a call
13be0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13bf0 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a  loc()] fails..**
13c00 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68  .** {H17406}  Th
13c10 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
13c20 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
13c30 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74   writes a zero-t
13c40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
13c50 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
13c60 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ing into the buf
13c70 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  fer pointed to b
13c80 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
13c90 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
13ca0 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61      provided tha
13cb0 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  t the first para
13cc0 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72  meter is greater
13cd0 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a   than zero..**.*
13ce0 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20  * {H17407}  The 
13cf0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
13d00 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  f()] interface d
13d10 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c  oes not write sl
13d20 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ots of.**       
13d30 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62      its output b
13d40 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e  uffer (the secon
13d50 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74  d parameter) out
13d60 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a  side the range.*
13d70 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30  *           of 0
13d80 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
13d90 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
13da0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
13db0 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72             regar
13dc0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e  dless of the len
13dd0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
13de0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  g.**           r
13df0 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20  equested by the 
13e00 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61  format specifica
13e10 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion..*/.char *s
13e20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
13e30 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
13e40 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
13e50 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
13e60 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
13e70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
13e80 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
13e90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
13ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13eb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13ec0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20  ation Subsystem 
13ed0 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30  {H17300} <S20000
13ee0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  >.**.** The SQLi
13ef0 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
13f00 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
13f10 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
13f20 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
13f30 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
13f40 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
13f50 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
13f60 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
13f70 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
13f80 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
13f90 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
13fa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
13fb0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
13fc0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
13fd0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
13fe0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
13ff0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
14000 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14010 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14020 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14030 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
14040 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
14050 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
14060 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
14070 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
14080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14090 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
140a0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
140b0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
140c0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
140d0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
140e0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
140f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
14100 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
14110 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
14120 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
14130 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
14140 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
14150 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
14160 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
14170 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
14180 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
14190 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
141a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
141b0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
141c0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
141d0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
141e0 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
141f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
14200 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
14210 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
14220 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
14230 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
14240 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
14250 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
14260 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
14270 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
14280 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
14290 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
142a0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
142b0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
142c0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
142d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
142e0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
142f0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
14300 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
14310 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
14320 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
14330 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
14340 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
14350 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
14360 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
14370 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
14380 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
14390 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
143a0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
143b0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
143c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
143d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a  qlite3_free()..*
143e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
143f0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
14400 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
14410 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
14420 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
14430 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
14440 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
14450 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
14460 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
14470 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
14480 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
14490 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
144a0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
144b0 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70    If the first p
144c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
144d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
144e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
144f0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
14500 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
14510 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
14520 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
14530 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
14540 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14550 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
14560 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68  lloc()..** If th
14570 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14580 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
14590 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
145a0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
145b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
145c0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
145d0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
145e0 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
145f0 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
14600 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14610 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
14620 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74  lloc()..** sqlit
14630 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
14640 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14650 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
14660 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
14670 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
14680 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
14690 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
146a0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
146b0 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65  ..** If M is the
146c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
146d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
146e0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
146f0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
14700 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
14710 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
14720 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
14730 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
14740 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
14750 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
14760 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
14770 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20  is freed..** If 
14780 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14790 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
147a0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
147b0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
147c0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
147d0 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75   The memory retu
147e0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
147f0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c  malloc() and sql
14800 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
14810 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
14820 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
14830 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
14840 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ry. {END}.**.** 
14850 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c  The default impl
14860 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
14870 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14880 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73  ion subsystem us
14890 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63  es.** the malloc
148a0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
148b0 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65  d free() provide
148c0 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72  d by the standar
148d0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
148e0 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72  {H17382} However
148f0 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
14900 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
14910 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52  .** SQLITE_MEMOR
14920 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69  Y_SIZE=<i>NNN</i
14930 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  > C preprocessor
14940 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69   macro (where <i
14950 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61  >NNN</i>.** is a
14960 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e  n integer), then
14970 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61   SQLite create a
14980 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66   static array of
14990 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e   at least.** <i>
149a0 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e  NNN</i> bytes in
149b0 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74   size and uses t
149c0 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c  hat array for al
149d0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
149e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
149f0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e  ation needs. {EN
14a00 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d  D}  Additional m
14a10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
14a20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62  options.** may b
14a30 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
14a40 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
14a50 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
14a60 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
14a70 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
14a80 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
14a90 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
14aa0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
14ab0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
14ac0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
14ad0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
14ae0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
14af0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
14b00 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
14b10 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
14b20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
14b30 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
14b40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14b50 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
14b60 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
14b70 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
14b80 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
14b90 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
14ba0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
14bb0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
14bc0 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
14bd0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
14be0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
14bf0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
14c00 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
14c10 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
14c20 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
14c30 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
14c40 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
14c50 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
14c60 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
14c70 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
14c80 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
14c90 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
14ca0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
14cb0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
14cc0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
14cd0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
14ce0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14cf0 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20 54  *.** {H17303}  T
14d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
14d10 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
14d20 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
14d30 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
14d40 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c            a newl
14d50 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c  y checked-out bl
14d60 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ock of at least 
14d70 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
14d80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  y.**           t
14d90 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
14da0 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74  igned, or it ret
14db0 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20  urns NULL if it 
14dc0 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  is unable.**    
14dd0 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c         to fulfil
14de0 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a  l the request..*
14df0 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20 54  *.** {H17304}  T
14e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
14e10 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  oc(N)] interface
14e20 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
14e30 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20  pointer if.**   
14e40 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73          N is les
14e50 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
14e60 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  to zero..**.** {
14e70 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71  H17305}  The [sq
14e80 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69  lite3_free(P)] i
14e90 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65  nterface release
14ea0 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75  s memory previou
14eb0 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
14ec0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
14ed0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14ee0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
14ef0 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
14f00 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74         making it
14f10 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72   available for r
14f20 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  euse..**.** {H17
14f30 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  306}  A call to 
14f40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55  [sqlite3_free(NU
14f50 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65  LL)] is a harmle
14f60 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
14f70 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c  {H17310}  A call
14f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
14f90 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71  lloc(0,N)] is eq
14fa0 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
14fb0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
14fc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
14fd0 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  oc(N)]..**.** {H
14fe0 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74  17312}  A call t
14ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
15000 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69  oc(P,0)] is equi
15010 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
15020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
15030 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
15040 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  )]..**.** {H1731
15050 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  5}  The SQLite c
15060 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65  ore uses [sqlite
15070 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
15080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15090 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  ,.**           a
150a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  nd [sqlite3_free
150b0 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ()] for all of i
150c0 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ts memory alloca
150d0 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
150e0 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69        deallocati
150f0 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  on needs..**.** 
15100 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73  {H17318}  The [s
15110 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
15120 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
15130 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
15140 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
15150 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20       to a block 
15160 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d  of checked-out m
15170 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
15180 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
15190 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
151a0 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c  hat is 8-byte al
151b0 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c  igned, or a NULL
151c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
151d0 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b  {H17321}  When [
151e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
151f0 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
15200 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
15210 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
15220 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74          copies t
15230 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73  he first K bytes
15240 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d   of content from
15250 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c   P into the newl
15260 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  y.**           a
15270 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20  llocated block, 
15280 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c  where K is the l
15290 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74  esser of N and t
152a0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20  he size of.**   
152b0 20 20 20 20 20 20 20 20 74 68 65 20 62 75 66 66          the buff
152c0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  er P..**.** {H17
152d0 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  322}  When [sqli
152e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
152f0 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  ] returns a non-
15300 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74  NULL pointer, it
15310 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
15320 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65      releases the
15330 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
15340 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e 20   {H17323}  When 
15350 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15360 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e  (P,N)] returns N
15370 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20  ULL, the buffer 
15380 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  P is.**         
15390 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f    not modified o
153a0 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  r released..**.*
153b0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
153c0 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20 54  *.** {A17350}  T
153d0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
153e0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
153f0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
15400 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75  .**           mu
15420 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
15430 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
15440 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
15450 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20   a prior.**     
15460 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
15470 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
15480 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
15490 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
154a0 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  at have.**      
154b0 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65       not yet bee
154c0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
154d0 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65 20  * {A17351}  The 
154e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
154f0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
15500 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
15510 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c  *           a bl
15520 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
15530 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
15540 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
15550 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
15560 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
15570 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15580 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ()]..*/.void *sq
15590 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
155a0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
155b0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
155c0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
155d0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
155e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
155f0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
15600 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48 31  r Statistics {H1
15610 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a  7370} <S30210>.*
15620 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
15630 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
15640 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
15650 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
15660 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
15670 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15680 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
15690 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
156a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
156b0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
156c0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
156d0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
156e0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
156f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15700 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d  :.**.** {H17371}
15710 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
15720 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
15730 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15740 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
15750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
15760 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
15770 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
15780 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
15790 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reed)..**.** {H1
157a0 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  7373} The [sqlit
157b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
157c0 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
157d0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
157e0 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  um.**          v
157f0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
15800 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
15810 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
15820 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
15830 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20 72        was last r
15840 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  eset..**.** {H17
15850 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73 20  374} The values 
15860 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
15870 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15880 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
15890 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d      [sqlite3_mem
158a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
158b0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
158c0 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20  rhead.**        
158d0 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74    added by SQLit
158e0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
158f0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
15900 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
15910 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20 6e  *          but n
15920 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
15930 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
15940 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
15950 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20 20  ibrary.**       
15960 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74     routines that
15970 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15980 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
15990 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68 65  .** {H17375} The
159a0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
159b0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
159c0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
159d0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
159e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
159f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
15a00 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
15a10 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15a20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
15a30 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15a40 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20  er()] is true.  
15a50 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
15a60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
15a70 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
15a80 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
15a90 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
15aa0 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
15ab0 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20     prior to the 
15ac0 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
15ad0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
15ae0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
15af0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
15b00 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
15b10 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
15b20 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
15b30 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
15b40 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
15b50 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39  Generator {H1739
15b60 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
15b70 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
15b80 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
15b90 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
15ba0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
15bb0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
15bc0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
15bd0 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73 65  ROWIDs when inse
15be0 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
15bf0 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
15c00 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
15c10 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
15c20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e 20  possible ROWID. 
15c30 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
15c40 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
15c50 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
15c60 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
15c70 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
15c80 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
15c90 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
15ca0 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
15cb0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
15cc0 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
15cd0 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  poses..**.** A c
15ce0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
15cf0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
15d00 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
15d10 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
15d20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
15d30 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
15d40 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
15d50 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
15d60 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
15d70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
15d80 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
15d90 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
15da0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
15db0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
15dc0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
15dd0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
15de0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e  s] object..** On
15df0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
15e00 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
15e10 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
15e20 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
15e30 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
15e40 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
15e50 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
15e60 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
15e70 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
15e80 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
15e90 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20  .**.** {H17392} 
15ea0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e  The [sqlite3_ran
15eb0 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e  domness(N,P)] in
15ec0 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 4e  terface writes N
15ed0 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
15ee0 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69        high-quali
15ef0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
15f00 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
15f10 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69   P..*/.void sqli
15f20 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
15f30 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
15f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15f50 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
15f60 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
15f70 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c  backs {H12500} <
15f80 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70100>.**.** Th
15f90 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
15fa0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
15fb0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
15fc0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
15fd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15fe0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
15ff0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
16000 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75  ument..** The au
16010 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16020 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
16030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
16040 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
16050 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
16060 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
16070 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
16080 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16090 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
160a0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
160b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
160c0 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
160d0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
160e0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
160f0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
16100 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
16110 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
16120 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
16130 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
16140 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16150 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
16160 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
16170 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
16180 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
16190 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
161a0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
161b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
161c0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
161d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
161e0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
161f0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
16200 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
16210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
16220 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
16230 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
16240 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
16250 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
16260 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
16270 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
16280 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
16290 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
162a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
162b0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
162c0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
162d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
162e0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
162f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
16300 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
16310 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16320 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16330 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
16340 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
16350 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
16360 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
16370 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
16380 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
16390 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
163a0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
163b0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
163c0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
163d0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
163e0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
163f0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
16400 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16410 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
16420 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
16430 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
16440 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
16450 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
16460 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
16470 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
16480 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
16490 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
164a0 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  er code is [SQLI
164b0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
164c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
164d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
164e0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
164f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
16500 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
16510 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
16520 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
16530 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
16540 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
16550 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
16560 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
16570 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
16580 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
16590 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
165a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
165b0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
165c0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
165d0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
165e0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
165f0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
16600 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20   a table..**.** 
16610 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
16620 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
16630 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16640 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
16650 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
16660 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
16670 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16680 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68  () interface. Th
16690 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
166a0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
166b0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
166c0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
166d0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
166e0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
166f0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
16700 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
16710 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
16720 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
16730 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
16740 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16750 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
16760 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
16770 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
16780 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
16790 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
167a0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
167b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
167c0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
167d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
167e0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
167f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
16800 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
16810 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
16820 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
16830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16840 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
16850 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
16860 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
16870 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
16880 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
16890 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
168a0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
168b0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
168c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
168d0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
168e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
168f0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
16900 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
16910 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
16920 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
16930 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
16940 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
16950 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
16960 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
16970 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
16980 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
16990 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
169a0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
169b0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
169c0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
169d0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
169e0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
169f0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
16a00 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
16a10 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
16a20 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
16a30 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
16a40 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
16a50 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
16a60 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
16a70 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
16a80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
16a90 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
16aa0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
16ab0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
16ac0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
16ad0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
16ae0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
16af0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
16b00 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
16b10 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
16b20 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
16b30 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
16b40 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73  ..**.** Only a s
16b50 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
16b60 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
16b70 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
16b80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
16b90 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
16ba0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
16bb0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
16bc0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
16bd0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
16be0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
16bf0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
16c00 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
16c10 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
16c20 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
16c30 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
16c40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
16c50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16c60 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16c70 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
16c80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16c90 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
16ca0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
16cb0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
16cc0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
16cd0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
16ce0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
16cf0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  step()]..**.** I
16d00 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16d10 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b 73   {H12501} The [s
16d20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16d30 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e  rizer(D,...)] in
16d40 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
16d50 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
16d60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16d70 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73  ack with databas
16d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
16d90 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20 54  **.** {H12502} T
16da0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16db0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16dc0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
16dd0 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  nts are.**      
16de0 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c      being compil
16df0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
16e00 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
16e10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
16e20 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
16e30 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
16e40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
16e50 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
16e60 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
16e70 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
16e80 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
16e90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16ea0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
16eb0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
16ec0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
16ed0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16ee0 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
16ef0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a  ll fail with an.
16f00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
16f10 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
16f20 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70   code and an app
16f30 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
16f40 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
16f50 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20  12504} When the 
16f60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16f70 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16f80 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
16f90 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ration.**       
16fa0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20     described is 
16fb0 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c  processed normal
16fc0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ly..**.** {H1250
16fd0 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68  5} When the auth
16fe0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16ff0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17000 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20  DENY], the.**   
17010 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17020 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
17030 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
17040 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
17050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
17060 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17070 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
17080 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  il.**          w
17090 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45  ith an [SQLITE_E
170a0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
170b0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
170c0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
170d0 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61    explaining tha
170e0 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  t access is deni
170f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
17100 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  6} If the author
17110 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
17120 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
17140 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
17150 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f  ack) is [SQLITE_
17160 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75  READ] and the au
17170 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17180 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  k returns.**    
17190 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
171a0 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20  NORE], then the 
171b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
171c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
171d0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
171e0 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76   insert a NULL v
171f0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
17200 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
17210 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
17220 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
17230 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
17240 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
17250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
17260 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20  {H12507} If the 
17270 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
17280 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
17290 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
172a0 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
172b0 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e   callback) is an
172c0 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ything other tha
172d0 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c  n [SQLITE_READ],
172e0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
172f0 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53    a return of [S
17300 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
17310 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
17320 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
17330 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  Y]..**.** {H1251
17340 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  0} The first par
17350 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
17360 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17370 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
17380 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
17390 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
173a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
173b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
173c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
173d0 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73  * {H12511} The s
173e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
173f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17400 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
17410 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
17420 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
17430 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
17440 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
17450 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
17460 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
17470 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
17480 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  H12512} The thir
17490 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
174a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
174b0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
174c0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
174d0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
174e0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a  gs that contain.
174f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69  **          addi
17500 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
17510 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
17520 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17530 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d  ..**.** {H12520}
17540 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
17550 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17560 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64  rizer()] overrid
17570 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
17580 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
17590 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
175a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  er..**.** {H1252
175b0 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
175c0 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
175d0 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
175e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
175f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
17600 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d  ..**.** {H12522}
17610 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
17620 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
17630 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
17640 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
17650 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
17660 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
17670 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
17680 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17690 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
176a0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
176b0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
176c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
176d0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
176e0 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48  odes {H12590} <H
176f0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
17700 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17710 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17720 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
17730 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
17740 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
17750 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
17760 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
17770 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
17780 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
17790 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
177a0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
177b0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
177c0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
177d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
177e0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
177f0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
17800 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
17810 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
17820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17830 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
17840 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17850 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
17860 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
17870 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
17880 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
17890 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
178a0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
178b0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
178c0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
178d0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
178e0 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e  H12550} <H12500>
178f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
17900 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17910 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
17920 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
17930 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
17940 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
17950 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
17960 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
17970 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
17980 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
17990 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
179a0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
179b0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
179c0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
179d0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
179e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
179f0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
17a00 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
17a10 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
17a20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17a30 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
17a40 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
17a50 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
17a60 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
17a70 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
17a80 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
17a90 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
17aa0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
17ab0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17ac0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
17ad0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
17ae0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
17af0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
17b00 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
17b10 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
17b20 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17b30 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
17b40 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
17b50 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
17b60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17b70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
17b80 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
17b90 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
17ba0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
17bb0 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
17bc0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17bd0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
17be0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
17bf0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
17c00 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
17c10 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
17c20 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
17c30 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
17c40 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
17c50 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
17c60 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
17c70 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
17c80 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  code..**.** INVA
17c90 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17ca0 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e  12551} The secon
17cb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  d parameter to a
17cc0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
17cd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ce0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17cf0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17d00 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65  always an intege
17d10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
17d20 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
17d30 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68  horizer code] th
17d40 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61  at specifies wha
17d50 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  t action.**     
17d60 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75       is being au
17d70 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17d80 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72 64  {H12552} The 3rd
17d90 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
17da0 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ers to the.**   
17db0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17dc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17dd0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
17de0 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20  allback].**     
17df0 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72       will be par
17e00 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
17e10 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
17e20 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ch.**          [
17e30 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
17e40 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69  thorizer code] i
17e50 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  cond parameter..
17e70 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54  **.** {H12553} T
17e80 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
17e90 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
17ea0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17eb0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17ec0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17ed0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
17ee0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
17ef0 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
17f00 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
17f10 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
17f20 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
17f30 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {H12554} The 6th
17f40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17f50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
17f60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17f70 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17f80 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17f90 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
17fa0 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
17fb0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
17fc0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
17fd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
17fe0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
17ff0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
18000 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
18010 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
18020 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
18030 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
18040 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
18050 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
18060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
18080 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
18090 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
180a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
180b0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
180c0 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
180d0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
180e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
180f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18100 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
18110 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
18120 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18130 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18150 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
18160 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
18170 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
18180 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18190 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
181a0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
181b0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
181c0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
181d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
181e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
181f0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
18200 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
18210 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18220 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18230 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18240 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18250 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
18260 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18270 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18280 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18290 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
182a0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
182b0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
182c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
182d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
182e0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
182f0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18300 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18310 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18320 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
18330 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
18340 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18350 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18360 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18370 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
18380 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
18390 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
183a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
183b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
183c0 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
183d0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
183e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
183f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18400 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18410 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
18420 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
18430 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
18440 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18460 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
18470 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
18480 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18490 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
184a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
184b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
184c0 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
184d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
184e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
184f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18500 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
18510 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
18520 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
18530 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18550 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
18560 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
18570 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
18580 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
185a0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
185b0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
185c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
185d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
185e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
185f0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
18600 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
18610 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18620 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
18640 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
18650 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
18660 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
18670 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
18680 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
18690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
186a0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
186b0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
186c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
186d0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
186e0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
186f0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
18700 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18710 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18720 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
18730 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
18740 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
18750 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18760 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18770 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
18780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
18790 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
187a0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
187b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
187c0 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
187d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
187e0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
187f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18800 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18810 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
18820 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
18830 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
18840 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
18850 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18860 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
18870 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
18880 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
18890 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
188a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
188b0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
188c0 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
188d0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
188e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
188f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18900 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
18910 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
18920 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18930 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18940 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18950 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
18960 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
18970 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18980 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
18990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
189a0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
189b0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
189c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
189d0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
189e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
189f0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
18a00 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
18a10 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
18a20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a40 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
18a50 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
18a60 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
18a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18a80 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
18a90 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
18aa0 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
18ab0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
18ac0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
18ad0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18ae0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
18af0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
18b00 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
18b10 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
18b20 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
18b30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
18b40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
18b50 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
18b60 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
18b70 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
18b80 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
18b90 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
18ba0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
18bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18bc0 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
18bd0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
18be0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
18bf0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18c00 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
18c10 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
18c20 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
18c30 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
18c40 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
18c50 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
18c60 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
18c70 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
18c80 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
18c90 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
18ca0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
18cb0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
18cc0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
18cd0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
18ce0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18cf0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18d00 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
18d10 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
18d20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
18d30 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
18d40 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
18d50 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
18d60 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
18d70 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
18d80 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
18d90 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
18da0 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
18db0 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
18dc0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   to run..**.** T
18dd0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
18de0 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
18df0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
18e00 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
18e10 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
18e20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
18e30 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65  oval in a future
18e40 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20   release..**.** 
18e50 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f  The trigger repo
18e60 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66  rting feature of
18e70 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
18e80 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ack is considere
18e90 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  d.** experimenta
18ea0 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
18eb0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
18ec0 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
18ed0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74  releases..** Fut
18ee0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
18ef0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
18f00 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20  o add new trace 
18f10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f  callback.** invo
18f20 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  cations..**.** I
18f30 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
18f40 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
18f50 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18f60 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18f70 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
18f80 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  is.**          w
18f90 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
18fa0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
18fb0 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
18fc0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18fd0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
18fe0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
18ff0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
19000 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  un..**.** {H1228
19010 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
19020 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
19030 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
19040 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
19050 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
19060 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
19070 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
19080 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
19090 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20  llback disables 
190a0 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
190b0 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  H12284} The firs
190c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
190d0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
190e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
190f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
19100 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
19110 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
19120 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
19130 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ce()]..**.** {H1
19140 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
19150 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19160 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
19170 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
19180 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19190 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
191a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
191b0 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
191c0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
191d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
191e0 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
191f0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
19200 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
19210 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
19220 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
19230 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
19240 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
19250 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
19260 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
19270 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
19280 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
19290 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
192a0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
192b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
192c0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
192d0 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
192e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
192f0 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  shes..**.** {H12
19300 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
19310 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19320 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
19330 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
19340 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
19350 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
19360 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19370 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
19380 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
19390 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
193a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
193b0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
193c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
193d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
193e0 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
193f0 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
19400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
19410 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
19420 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
19430 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
19440 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
19450 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
19460 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
19470 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74  * {H12290} The t
19480 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
19490 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
194a0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
194b0 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
194c0 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
194d0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
194e0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
194f0 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
19500 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
19510 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
19520 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
19530 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  nish..*/.void *s
19540 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
19550 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
19560 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
19570 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
19580 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70  .void *sqlite3_p
19590 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
195a0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
195b0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
195c0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
195d0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
195e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
195f0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
19600 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30  allbacks {H12910
19610 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
19620 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
19630 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
19640 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
19650 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
19660 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
19670 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
19680 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
19690 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
196a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
196b0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
196c0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
196d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
196e0 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
196f0 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
19700 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
19710 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
19720 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
19730 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
19740 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
19750 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
19760 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
19770 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
19780 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
19790 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
197a0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
197b0 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
197c0 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
197d0 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  GUI dialog box..
197e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
197f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d  :.**.** {H12911}
19800 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
19810 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19820 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
19830 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a  gress_handler().
19840 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
19850 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
19860 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
19870 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
19880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
19890 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
198a0 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 68  *.** {H12912} Th
198b0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
198c0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
198d0 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
198e0 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
198f0 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
19900 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
19910 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19920 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
19930 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
19940 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
19950 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
19960 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
19970 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
19980 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  k.  If N is less
19990 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33   than 1, sqlite3
199a0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
199b0 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
199c0 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c  acts as if a NUL
199d0 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  L progress handl
199e0 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 63  er had been spec
199f0 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ified..**.** {H1
19a00 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65  2913} The progre
19a10 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65  ss callback itse
19a20 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
19a30 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   by the third.**
19a40 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
19a50 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
19a60 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19a70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d  ..**.** {H12914}
19a80 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
19a90 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
19aa0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
19ab0 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  () is a.**      
19ac0 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72      void pointer
19ad0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
19ae0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
19af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
19b00 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
19b10 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
19b20 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 66  *.** {H12915} If
19b30 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
19b40 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75  te3_step()] resu
19b50 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
19b60 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20  n N opcodes.**  
19b70 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 78          being ex
19b80 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65  ecuted, then the
19b90 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19ba0 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
19bb0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
19bc0 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
19bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
19be0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
19bf0 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
19c00 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
19c10 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20  usly registered 
19c20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
19c30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d  ..**.** {H12917}
19c40 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
19c50 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
19c60 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
19c70 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
19c80 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
19c90 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
19ca0 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68 65   {H12918} If the
19cb0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
19cc0 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
19cd0 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
19ce0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
19cf0 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
19d00 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
19d10 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
19d20 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
19d30 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33 30 35  *          <S305
19d40 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  00>.*/.void sqli
19d50 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19d60 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
19d70 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
19d80 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19d90 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
19da0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
19db0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
19dc0 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a  12700} <S40200>.
19dd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19de0 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
19df0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
19e00 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
19e10 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
19e20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19e30 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  t. The filename 
19e40 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
19e50 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
19e60 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19e70 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19e80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
19e90 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
19ea0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
19eb0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
19ec0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b  e3_open16(). A [
19ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ee0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
19ef0 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
19f00 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
19f10 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
19f20 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
19f30 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
19f40 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
19f50 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
19f60 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
19f70 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
19f80 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
19f90 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
19fa0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
19fb0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
19fc0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
19fd0 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20  te3].** object. 
19fe0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
19ff0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
1a000 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
1a010 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
1a020 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1a030 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
1a040 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1a050 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1a060 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
1a070 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
1a080 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1a090 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
1a0a0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
1a0b0 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
1a0c0 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
1a0d0 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
1a0e0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ror..**.** The d
1a0f0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
1a100 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
1a110 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
1a120 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
1a130 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1a140 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
1a150 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
1a160 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a170 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
1a180 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
1a190 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
1a1a0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
1a1b0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
1a1c0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
1a1d0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
1a1e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1a1f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a200 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
1a210 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
1a220 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
1a230 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
1a240 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
1a250 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
1a260 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
1a270 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a280 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
1a290 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
1a2a0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
1a2b0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
1a2c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
1a2d0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
1a2e0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
1a2f0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
1a300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a310 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20  ion.  The flags 
1a320 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61  parameter can ta
1a330 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1a340 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1a350 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1a360 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1a370 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1a380 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1a390 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  flag:.**.** <dl>
1a3a0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1a3b0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1a3c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a3d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a3e0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1a3f0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1a400 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a410 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1a420 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1a430 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  urned.</dd>.**.*
1a440 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1a450 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
1a460 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1a470 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1a480 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1a490 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1a4a0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
1a4b0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
1a4c0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
1a4d0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
1a4e0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
1a4f0 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
1a500 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
1a510 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
1a520 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
1a530 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1a540 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1a550 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1a560 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1a570 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1a580 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1a590 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a5a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1a5b0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1a5c0 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
1a5d0 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1a5e0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1a5f0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1a600 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1a610 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1a620 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a630 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1a640 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  n16().</dd>.** <
1a650 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1a660 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1a670 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1a680 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1a690 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1a6a0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1a6b0 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1a6c0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1a6d0 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1a6e0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1a6f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a700 54 45 58 5d 20 66 6c 61 67 2c 20 74 68 65 6e 20  TEX] flag, then 
1a710 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1a720 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1a730 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
1a740 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1a750 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1a760 6d 75 74 65 78 65 73 20 6f 6e 20 74 68 65 0a 2a  mutexes on the.*
1a770 2a 20 6f 70 65 6e 65 64 20 5b 64 61 74 61 62 61  * opened [databa
1a780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1a790 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  re disabled and 
1a7a0 74 68 65 20 61 70 70 6c 69 61 74 69 6f 6e 20 6d  the appliation m
1a7b0 75 73 74 0a 2a 2a 20 69 6e 73 75 72 65 20 74 68  ust.** insure th
1a7c0 61 74 20 61 63 63 65 73 73 20 74 6f 20 74 68 65  at access to the
1a7d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a7e0 63 74 69 6f 6e 5d 20 61 6e 64 20 69 74 73 20 61  ction] and its a
1a7f0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 5b 70 72  ssociated.** [pr
1a800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1a810 73 5d 20 69 73 20 73 65 72 69 61 6c 69 7a 65 64  s] is serialized
1a820 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
1a830 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1a840 67 0a 2a 2a 20 69 73 20 74 68 65 20 64 65 66 61  g.** is the defa
1a850 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ult behavior is 
1a860 53 51 4c 69 74 65 20 69 73 20 63 6f 6e 66 69 67  SQLite is config
1a870 75 72 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ured using the.*
1a880 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
1a890 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 20 6f 72  _MULTITHREAD] or
1a8a0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1a8b0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 70  SINGLETHREAD] op
1a8c0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tions.** to [sql
1a8d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 20  ite3_config()]. 
1a8e0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
1a8f0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1a900 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 0a 2a 2a 20  only makes a.** 
1a910 64 69 66 66 65 72 65 6e 63 65 20 77 68 65 6e 20  difference when 
1a920 53 51 4c 69 74 65 20 69 73 20 69 6e 20 69 74 73  SQLite is in its
1a930 20 64 65 66 61 75 6c 74 20 5b 53 51 4c 49 54 45   default [SQLITE
1a940 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
1a950 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ED] mode..**.** 
1a960 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1a970 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1a980 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1a990 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1a9a0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1a9b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1a9c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1a9d0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1a9e0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1a9f0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1aa00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa10 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1aa20 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1aa30 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1aa40 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1aa50 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1aa60 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1aa70 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1aa80 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1aa90 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1aaa0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1aab0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1aac0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1aad0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1aae0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1aaf0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1ab00 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1ab10 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1ab20 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1ab30 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1ab40 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1ab50 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1ab60 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1ab70 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1ab80 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1ab90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1aba0 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
1abb0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1abc0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1abd0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1abe0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1abf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ac00 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1ac10 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
1ac20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ac30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ac40 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1ac50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1ac60 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1ac70 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1ac80 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1ac90 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1aca0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1acb0 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1acc0 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
1acd0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1ace0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1acf0 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1ad00 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1ad10 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1ad20 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1ad30 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1ad40 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1ad50 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1ad60 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1ad70 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1ad80 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ad90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1ada0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1adb0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1adc0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1add0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1ade0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1adf0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1ae00 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1ae10 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1ae20 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1ae30 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1ae40 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1ae50 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1ae60 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1ae70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1ae80 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68  *.** {H12701} Th
1ae90 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1aea0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1aeb0 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
1aec0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1aed0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1aee0 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20  rfaces create a 
1aef0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1af00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1af10 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
1af20 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1af30 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66    the database f
1af40 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
1af50 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ir first paramet
1af60 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  er..**.** {H1270
1af70 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  2} The filename 
1af80 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1af90 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1afa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1afb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1afc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
1afd0 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
1afe0 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
1aff0 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
1b000 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
1b010 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1b020 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ()]..**.** {H127
1b030 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
1b040 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1b050 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1b060 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1b070 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1b080 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1b090 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
1b0a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1b0b0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1b0c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b0d0 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
1b0e0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54  **.** {H12704} T
1b0f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1b100 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b110 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1b120 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b130 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1b140 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
1b150 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
1b160 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
1b170 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
1b180 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1b190 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
1b1a0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54  **.** {H12706} T
1b1b0 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
1b1c0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
1b1d0 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
1b1e0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
1b1f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1b200 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
1b210 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
1b220 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
1b230 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20  ** {H12707} The 
1b240 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1b250 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1b260 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1b270 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1b280 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1b290 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
1b2a0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  F-16..**.** {H12
1b2b0 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
1b2c0 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
1b2d0 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
1b2e0 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
1b2f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1b300 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
1b310 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
1b320 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
1b330 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
1b340 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
1b350 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1b360 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d  ..**.** {H12711}
1b370 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1b380 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b390 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1b3a0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1b3b0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1b3c0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1b3d0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
1b3e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1b3f0 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1b400 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
1b410 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  only..**.** {H12
1b420 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
1b430 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b440 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1b450 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b460 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b470 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b480 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1b490 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1b4a0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1b4b0 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
1b4c0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1b4d0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
1b4e0 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
1b4f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1b500 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1b510 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1b520 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1b530 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d  ..**.** {H12713}
1b540 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1b550 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1b560 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29  open(v2(F,D,G,V)
1b570 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
1b580 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1b590 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1b5a0 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1b5b0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1b5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1b5d0 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
1b5e0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1b5f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ned..**.** {H127
1b600 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
1b610 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1b620 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47  e3_open(v2(F,D,G
1b630 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1b640 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1b650 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1b660 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1b670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1b680 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1b690 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1b6a0 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
1b6b0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b6c0 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
1b6d0 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
1b6e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
1b6f0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49  **.** {H12717} I
1b700 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
1b710 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1b720 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1b730 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1b740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1b750 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b760 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
1b770 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
1b780 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1b790 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
1b7a0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
1b7b0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1b7c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
1b7d0 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1b7e0 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1b7f0 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1b800 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1b810 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1b820 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1b830 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1b840 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74  ** {H12719} If t
1b850 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
1b860 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
1b870 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1b880 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1b890 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e      ephemeral on
1b8a0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1b8b0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a  ill be created..
1b8c0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1b8d0 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
1b8e0 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
1b8f0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
1b900 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
1b910 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
1b920 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
1b930 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54  **.** {H12721} T
1b940 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1b950 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64  nection] created
1b960 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   by [sqlite3_ope
1b970 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a  n_v2(F,D,G,V)].*
1b980 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
1b990 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1b9a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65  _vfs] object ide
1b9b0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56  ntified by the V
1b9c0 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20   parameter,.**  
1b9d0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64          or the d
1b9e0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1b9f0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56  vfs] object if V
1ba00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ba10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  er..**.** {H1272
1ba20 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65  3} Two [database
1ba30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69   connections] wi
1ba40 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f  ll share a commo
1ba50 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20  n cache if both 
1ba60 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  were.**         
1ba70 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65   opened with the
1ba80 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20   same VFS while 
1ba90 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1baa0 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20  de] was enabled 
1bab0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1bac0 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65  if both filename
1bad0 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  s compare equal 
1bae0 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61  using memcmp() a
1baf0 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1bb00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f  .**          pro
1bb10 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73  cessed by the [s
1bb20 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75  qlite3_vfs | xFu
1bb30 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68  llPathname] meth
1bb40 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a  od of the VFS..*
1bb50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1bb60 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1bb70 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1bb80 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1bb90 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1bba0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1bbb0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1bbc0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1bbd0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1bbe0 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1bbf0 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1bc00 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1bc10 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1bc20 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1bc30 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1bc40 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1bc50 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1bc60 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1bc70 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1bc80 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1bc90 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1bca0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1bcb0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1bcc0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1bcd0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1bce0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1bcf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1bd00 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1bd10 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1bd20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1bd30 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1bd40 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1bd50 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1bd60 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1bd70 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
1bd80 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
1bd90 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1bda0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1bdb0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1bdc0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1bdd0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1bde0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1bdf0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1be00 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1be10 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1be20 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1be30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1be40 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1be50 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1be60 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1be70 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1be80 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1be90 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1bea0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1beb0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1bec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1bed0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
1bee0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1bef0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
1bf00 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
1bf10 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1bf20 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
1bf30 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1bf40 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1bf50 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74  ely..** Memory t
1bf60 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1bf70 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1bf80 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1bf90 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1bfa0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1bfb0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1bfc0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1bfd0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1bfe0 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1bff0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1c000 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1c010 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1c020 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1c030 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1c040 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1c050 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  ctions..**.** If
1c060 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1c070 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1c080 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1c090 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1c0a0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1c0b0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1c0c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1c0d0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1c0e0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1c0f0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1c100 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1c110 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
1c120 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1c130 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1c140 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1c150 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1c160 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1c170 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20          [result 
1c180 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
1c190 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1c1a0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1c1b0 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
1c1c0 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61    failed interfa
1c1d0 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1c1e0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1c1f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c200 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ] D..**.** {H128
1c210 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
1c220 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20  _errmsg(D)] and 
1c230 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1c240 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  6(D)].**        
1c250 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74    interfaces ret
1c260 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1c270 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64  uage text that d
1c280 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20  escribes.**     
1c290 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69       the error i
1c2a0 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63  n the mostly rec
1c2b0 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74  ently failed int
1c2c0 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20  erface call,.** 
1c2d0 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64           encoded
1c2e0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c2f0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1c300 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ctively..**.** {
1c310 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69  H12807} The stri
1c320 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c330 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1c340 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c350 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20  errmsg16()].**  
1c360 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69          are vali
1c370 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
1c380 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1c390 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e call..**.** {H
1c3a0 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20  12808} Calls to 
1c3b0 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61  API routines tha
1c3c0 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20  t do not return 
1c3d0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  an error code.**
1c3e0 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70            (examp
1c3f0 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  le: [sqlite3_dat
1c400 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e  a_count()]) do n
1c410 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ot.**          c
1c420 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20  hange the error 
1c430 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20  code or message 
1c440 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1c450 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c460 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
1c470 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
1c480 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1c490 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  msg16()]..**.** 
1c4a0 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61  {H12809} Interfa
1c4b0 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74  ces that are not
1c4c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c4d0 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20   a specific.**  
1c4e0 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1c4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65  e connection] (e
1c500 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20  xamples:.**     
1c510 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70       [sqlite3_mp
1c520 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c  rintf()] or [sql
1c530 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1c540 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20  ed_cache()].**  
1c550 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63          do not c
1c560 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
1c570 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c580 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c590 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1c5a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c5b0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1c5c0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  rmsg16()]..*/.in
1c5d0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1c5e0 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1c5f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1c600 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1c610 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1c620 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1c630 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1c640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1c650 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1c660 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31  ect {H13000} <H1
1c670 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  3010>.** KEYWORD
1c680 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1c690 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1c6a0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1c6b0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1c6c0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1c6d0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1c6e0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1c6f0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1c700 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1c710 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1c720 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1c730 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1c740 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1c750 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1c760 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1c770 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1c780 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1c790 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1c7a0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1c7b0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1c7c0 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1c7d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1c7e0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1c7f0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1c800 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1c810 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1c820 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1c830 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1c840 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1c850 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1c860 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1c870 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1c880 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1c890 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1c8a0 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1c8b0 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1c8c0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c8d0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1c8e0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1c8f0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1c900 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1c910 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1c920 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1c930 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c940 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1c950 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1c960 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1c970 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1c980 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1c990 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1c9a0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1c9b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1c9c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1c9d0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1c9e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1c9f0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31  -time Limits {H1
1ca00 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a  2760} <S20600>.*
1ca10 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
1ca20 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1ca30 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1ca40 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1ca50 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1ca60 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1ca70 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1ca80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1ca90 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1caa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cab0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1cac0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1cad0 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1cae0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1caf0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1cb00 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1cb10 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1cb20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1cb30 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1cb40 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1cb50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1cb60 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1cb70 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1cb80 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1cb90 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1cba0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a  the old limit..*
1cbb0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20  *.** If the new 
1cbc0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1cbd0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1cbe0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1cbf0 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c  ed..** For the l
1cc00 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66  imit category of
1cc10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59   SQLITE_LIMIT_XY
1cc20 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61 72  Z there is a har
1cc30 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64  d upper.** bound
1cc40 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1cc50 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1cc60 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1cc70 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  d SQLITE_MAX_XYZ
1cc80 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1cc90 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1cca0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1ccb0 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d  MAX_".).** Attem
1ccc0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1ccd0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1cce0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1ccf0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1cd00 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1cd10 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
1cd20 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20  imit..**.** Run 
1cd30 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
1cd40 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
1cd50 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
1cd60 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
1cd70 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
1cd80 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1cd90 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
1cda0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
1cdb0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
1cdc0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
1cdd0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
1cde0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
1cdf0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
1ce00 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74 20  webbrowser that 
1ce10 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1ce20 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1ce30 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1ce40 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1ce50 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1ce60 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1ce70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1ce80 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1ce90 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1cea0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1ceb0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1cec0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1ced0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1cee0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1cef0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1cf00 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1cf10 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1cf20 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1cf30 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1cf40 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1cf50 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1cf60 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1cf70 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1cf80 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1cf90 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1cfa0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1cfb0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1cfc0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1cfd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1cfe0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1cff0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1d000 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1d010 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1d020 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1d030 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1d040 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1d050 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1d060 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1d070 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1d080 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ases..**.** INVA
1d090 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1d0a0 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73 73  12762} A success
1d0b0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1d0c0 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1d0d0 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a  )] where V is.**
1d0e0 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74 69            positi
1d0f0 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  ve changes the l
1d100 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1d110 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1d120 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1d130 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1d140 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68  nection] D to th
1d150 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e  e lesser of V an
1d160 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  d the hard upper
1d170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75  .**          bou
1d180 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  nd on the size o
1d190 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74 20  f C that is set 
1d1a0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
1d1b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20  .**.** {H12766} 
1d1c0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1d1d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1d1e0 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
1d1f0 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a  e V is negative.
1d200 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61 76  **          leav
1d210 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20  es the state of 
1d220 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1d230 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68  nnection] D unch
1d240 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anged..**.** {H1
1d250 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73 66  2769} A successf
1d260 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1d270 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1d280 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  ] returns the.**
1d290 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
1d2a0 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  of the limit on 
1d2b0 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
1d2c0 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a  truct C in the.*
1d2d0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1d2e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d2f0 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72 69   D as it was pri
1d300 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a  or to the call..
1d310 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
1d320 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
1d330 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
1d340 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1d350 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1d360 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b  mit Categories {
1d370 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e  H12790} <H12760>
1d380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
1d390 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
1d3a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1d3b0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1d3c0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1d3d0 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f  arious aspects o
1d3e0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
1d3f0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
1d400 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64  t can be limited
1d410 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c   in size by call
1d420 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  s to [sqlite3_li
1d430 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d  mit()]..** The m
1d440 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1d450 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72  arious limits ar
1d460 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
1d470 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1d480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1d490 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1d4a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1d4b0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1d4c0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1d4d0 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
1d4e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d4f0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1d500 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d510 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1d520 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1d530 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1d540 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d550 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1d560 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d570 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1d580 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1d590 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1d5a0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
1d5b0 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78  ELECT or the max
1d5c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1d5d0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1d5e0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1d5f0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1d600 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1d610 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d620 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1d630 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d640 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1d650 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1d660 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1d670 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1d680 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d690 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d6a0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1d6b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d6c0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1d6d0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1d6e0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1d6f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d700 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1d710 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d720 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d730 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1d740 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1d750 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1d760 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1d770 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1d780 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1d790 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1d7a0 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1d7b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d7c0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1d7d0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1d7e0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1d7f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d800 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1d810 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d820 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61  m number of atta
1d830 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c  ched databases.<
1d840 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1d850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1d860 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1d870 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d880 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1d890 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1d8a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49  gument to the LI
1d8b0 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70  KE or.** GLOB op
1d8c0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
1d8d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d8e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1d8f0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1d900 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d910 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1d920 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1d930 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1d940 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
1d950 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1d960 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d970 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1d980 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1d990 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d9a0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1d9b0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1d9c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d9d0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1d9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1d9f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1da00 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1da10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1da20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1da30 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1da40 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1da50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1da60 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1da70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1da80 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1da90 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1daa0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1dab0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1dac0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1dad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dae0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1daf0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1db00 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1db10 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1db20 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1db30 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1db40 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
1db50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1db60 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1db70 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30  t {H13010} <S100
1db80 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1db90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1dba0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1dbb0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1dbc0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1dbd0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1dbe0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1dbf0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1dc00 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1dc10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1dc20 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1dc30 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1dc40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dc50 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1dc60 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1dc70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1dc80 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1dc90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
1dca0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dcb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
1dcc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1dcd0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1dce0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1dcf0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1dd00 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1dd10 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1dd20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1dd30 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1dd40 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1dd50 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1dd60 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1dd70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1dd80 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1dd90 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1dda0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1ddb0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1ddc0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1ddd0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1dde0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1ddf0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1de00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49  ro terminator. I
1de10 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1de20 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1de30 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1de40 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1de50 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1de60 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
1de70 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1de80 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1de90 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1dea0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1deb0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1dec0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1ded0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1dee0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1def0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1df00 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1df10 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1df20 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1df30 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1df40 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1df50 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1df60 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1df70 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1df80 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1df90 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1dfa0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1dfb0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1dfc0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1dfd0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1dfe0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1dff0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1e000 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69  .**.** *pzTail i
1e010 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1e020 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1e030 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  e past the end o
1e040 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53  f the.** first S
1e050 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1e060 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1e070 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69  tines only compi
1e080 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  le the first.** 
1e090 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1e0a0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1e0b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1e0c0 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a  o what remains.*
1e0d0 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  * uncompiled..**
1e0e0 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c  .** *ppStmt is l
1e0f0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1e100 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1e110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e120 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1e130 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1e140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1e150 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   If there is an 
1e160 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1e170 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1e180 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74 20  .  If the input 
1e190 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
1e1a0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
1e1b0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
1e1c0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
1e1d0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
1e1e0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
1e1f0 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20  LL..** {A13018} 
1e200 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
1e210 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
1e220 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
1e230 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
1e240 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1e250 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1e260 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
1e270 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
1e280 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20   with it..**.** 
1e290 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
1e2a0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1e2b0 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ned, otherwise a
1e2c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1e2d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1e2e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
1e2f0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
1e300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1e310 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
1e320 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
1e330 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
1e340 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
1e350 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
1e360 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
1e370 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
1e380 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1e390 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
1e3a0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
1e3b0 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
1e3c0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
1e3d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
1e3e0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
1e3f0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
1e400 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
1e410 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
1e420 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
1e430 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
1e440 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
1e450 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
1e460 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
1e470 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e 74  have a different
1e480 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a  ly in two ways:.
1e490 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1e4a0 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  i>.** If the dat
1e4b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1e4c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1e4d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1e4e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1e4f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1e500 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1e510 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1e520 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1e530 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1e540 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1e550 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1e560 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65 6d  n.  If the schem
1e570 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e  a has changed in
1e580 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d  .** a way that m
1e590 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65  akes the stateme
1e5a0 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c  nt no longer val
1e5b0 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  id, [sqlite3_ste
1e5c0 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a  p()] will still.
1e5d0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
1e5e0 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20  E_SCHEMA].  But 
1e5f0 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63  unlike the legac
1e600 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c  y behavior, [SQL
1e610 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a  ITE_SCHEMA] is.*
1e620 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72  * now a fatal er
1e630 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73  ror.  Calling [s
1e640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e650 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20  2()] again will 
1e660 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20  not make the.** 
1e670 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20  error go away.  
1e680 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74  Note: use [sqlit
1e690 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20  e3_errmsg()] to 
1e6a0 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a  find the text.**
1e6b0 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20   of the parsing 
1e6c0 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c  error that resul
1e6d0 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  ts in an [SQLITE
1e6e0 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e  _SCHEMA] return.
1e6f0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1e700 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20  <li>.** When an 
1e710 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1e720 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1e730 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1e740 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1e750 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1e760 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1e770 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20  or codes].  The 
1e780 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e790 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e7a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e7b0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e7c0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e7d0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e7e0 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77  ode.** and you w
1e7f0 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1e800 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1e810 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1e820 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  t()] in order.**
1e830 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1e840 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1e850 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1e860 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1e870 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1e880 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1e890 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1e8a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e8b0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1e8c0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1e8d0 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
1e8e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  TS:.**.** {H1301
1e8f0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1e900 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c  prepare(db,zSql,
1e910 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
1e920 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1e930 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1e940 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
1e950 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
1e960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
1e970 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
1e980 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
1e990 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  -8..**.** {H1301
1e9a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
1e9b0 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71  prepare16(db,zSq
1e9c0 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20  l,...)] and.**  
1e9d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e9e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64 62  _prepare16_v2(db
1e9f0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1ea00 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1ea10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ea20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1ea30 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1ea40 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1ea50 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1ea60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d  ..**.** {H13013}
1ea70 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1ea80 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1ea90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1eaa0 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
1eab0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
1eac0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
1ead0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1eae0 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20 69  , the SQL text i
1eaf0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  s.**          re
1eb00 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20  ad from zSql is 
1eb10 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20 66  read up to the f
1eb20 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1eb30 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ator..**.** {H13
1eb40 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74  014} If the nByt
1eb50 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1eb60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1eb70 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1eb80 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1eb90 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1eba0 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ts is non-negati
1ebb0 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74  ve, then at most
1ebc0 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f 66   nBytes bytes of
1ebd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
1ebe0 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66 72   text is read fr
1ebf0 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  om zSql..**.** {
1ec00 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69  H13015} In [sqli
1ec10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1ec20 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69  b,zSql,N,P,pzTai
1ec30 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  l)] and its vari
1ec40 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ants.**         
1ec50 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70   if the zSql inp
1ec60 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1ec70 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53   more than one S
1ec80 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
1ec90 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54           and pzT
1eca0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ail is not NULL,
1ecb0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1ecc0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1ecd0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
1ece0 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73    first byte pas
1ecf0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1ed00 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1ed10 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a  ment in zSql..**
1ed20 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1ed30 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69  What does *pzTai
1ed40 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68  l point to if th
1ed50 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65  ere is one state
1ed60 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  ment?</todo>.**.
1ed70 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73 75  ** {H13016} A su
1ed80 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1ed90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1eda0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70  e_v2(db,zSql,N,p
1edb0 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  pStmt,...)].**  
1edc0 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f          or one o
1edd0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 77  f its variants w
1ede0 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74  rites into *ppSt
1edf0 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  mt a pointer to 
1ee00 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1ee10 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1ee20 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e  ement] or a poin
1ee30 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a  ter to NULL if z
1ee40 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  Sql contains.** 
1ee50 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67           nothing
1ee60 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
1ee70 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e  espace or commen
1ee80 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  ts..**.** {H1301
1ee90 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1eea0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e  prepare_v2()] in
1eeb0 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73 20  terface and its 
1eec0 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a  variants return.
1eed0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1eee0 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70  ITE_OK] or an ap
1eef0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
1ef00 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c   code] upon fail
1ef10 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  ure..**.** {H130
1ef20 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69  21} Before [sqli
1ef30 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1ef40 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74  Sql,nByte,ppStmt
1ef50 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73  ,pzTail)] or its
1ef60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 72  .**          var
1ef70 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e  iants returns an
1ef80 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75   error (any valu
1ef90 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
1efa0 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20  LITE_OK]),.**   
1efb0 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72 73         they firs
1efc0 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f  t set *ppStmt to
1efd0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
1efe0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
1eff0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f000 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f010 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f020 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f030 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f040 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1f050 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f060 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f070 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f080 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f090 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f0a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f0b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f0c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f0d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f0e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f0f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f100 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f110 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1f120 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f130 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1f140 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1f150 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1f160 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1f170 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1f180 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1f190 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1f1a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f1b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f1c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f1d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f1e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f1f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f200 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f210 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f220 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1f230 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f240 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f250 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1f270 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
1f280 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f290 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1f2a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f2b0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1f2c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1f2d0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1f2e0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1f2f0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1f300 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1f310 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1f320 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1f330 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1f340 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1f350 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1f360 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1f370 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1f380 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1f390 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1f3a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1f3b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f3c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
1f3d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f3e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f3f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f400 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f420 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1f430 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1f440 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1f450 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1f460 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1f470 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1f480 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1f490 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1f4a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1f4b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1f4c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1f4d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1f4e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1f4f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46  ;../*.** CAPIREF
1f500 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1f510 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31  tement SQL {H131
1f520 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a  00} <H13000>.**.
1f530 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1f540 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1f550 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
1f560 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
1f570 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
1f580 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
1f590 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
1f5a0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
1f5b0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
1f5c0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
1f5d0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
1f5e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1f5f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1f600 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1f610 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f620 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20  .** {H13101} If 
1f630 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f640 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20  atement] passed 
1f650 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  as the argument 
1f660 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1f670 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77  sqlite3_sql()] w
1f680 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  as compiled usin
1f690 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1f6a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f6b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1f6c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f6d0 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73  6_v2()], then [s
1f6e0 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1f6f0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
1f700 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    a pointer to a
1f710 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1f720 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
1f730 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ng a UTF-8 rende
1f740 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
1f750 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1f760 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f770 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49  **.** {H13102} I
1f780 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1f790 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65  statement] passe
1f7a0 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e  d as the argumen
1f7b0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1f7c0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
1f7d0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73   was compiled us
1f7e0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1f7f0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f800 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
1f810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f820 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ()], then [sqlit
1f830 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e  e3_sql()] return
1f840 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f850 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d  ..**.** {H13103}
1f860 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75   The string retu
1f870 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f880 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69  _sql(S)] is vali
1f890 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20  d until the.**  
1f8a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f8b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
1f8c0 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  s deleted using 
1f8d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f8e0 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  e(S)]..*/.const 
1f8f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1f900 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1f910 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1f920 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1f930 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1f940 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d   Object {H15000}
1f950 20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b   .** KEYWORDS: {
1f960 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1f970 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1f980 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f990 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1f9a0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1f9b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1f9c0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1f9d0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1f9e0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1f9f0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1fa00 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1fa10 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1fa20 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1fa30 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
1fa40 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1fa50 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fa60 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1fa70 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1fa80 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1fa90 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1faa0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1fab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1fac0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1fad0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1fae0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1faf0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1fb00 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1fb10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1fb20 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1fb30 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1fb40 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1fb50 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1fb60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1fb70 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1fb80 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1fb90 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1fba0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1fbb0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1fbc0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1fbd0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1fbe0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1fbf0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1fc00 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1fc10 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1fc20 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1fc30 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1fc40 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1fc50 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1fc60 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1fc70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1fc80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fc90 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1fca0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1fcb0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1fcc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fcd0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1fce0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1fcf0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1fd00 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1fd10 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1fd20 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1fd30 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1fd40 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1fd50 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1fd60 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1fd70 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1fd80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1fd90 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1fda0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1fdb0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1fdc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1fdd0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1fde0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1fdf0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1fe00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1fe10 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1fe20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1fe30 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1fe40 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1fe50 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1fe60 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1fe70 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1fe80 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1fe90 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1fea0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1feb0 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1fec0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1fed0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1fee0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1fef0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1ff00 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1ff10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1ff20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ff30 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1ff40 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1ff50 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1ff60 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1ff70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ff80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ff90 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1ffa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ffb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1ffc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1ffd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1ffe0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1fff0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
20000 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20010 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
20020 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
20030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
20040 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
20050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
20060 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
20070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
20080 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
20090 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
200a0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
200b0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
200c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
200d0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
200e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
200f0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
20100 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20110 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
20120 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
20130 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16001}.**.** The
20140 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
20150 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
20160 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
20170 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
20180 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
20190 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
201a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
201b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
201c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
201d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
201e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
201f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
20200 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
20210 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
20220 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
20230 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
20240 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
20250 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
20260 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
20270 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
20280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
20290 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
202a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
202b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
202c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
202d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
202e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
202f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
20300 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
20310 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20320 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
20330 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
20340 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
20350 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
20360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
20370 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
20380 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
20390 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37  nts {H13500} <S7
203a0 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0000>.** KEYWORD
203b0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
203c0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
203d0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
203e0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
203f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
20400 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
20410 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
20420 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
20430 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
20440 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
20450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20460 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
20470 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
20480 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
20490 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65  aced by a parame
204a0 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  ter in one of th
204b0 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
204c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
204d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
204e0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
204f0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
20500 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
20510 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
20520 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
20530 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
20540 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
20550 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
20560 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d   is an alpha-num
20570 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
20580 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ame. The values 
20590 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
205a0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
205b0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
205c0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
205d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
205e0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
205f0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
20600 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
20610 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
20620 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
20630 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
20640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20650 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
20660 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
20670 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20680 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
20690 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
206a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
206b0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
206c0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
206d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
206e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
206f0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
20700 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
20710 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
20720 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
20730 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
20740 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
20750 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
20760 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
20770 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
20780 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
20790 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
207a0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
207b0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
207c0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
207d0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
207e0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
207f0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
20800 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
20810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20820 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
20830 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
20840 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
20850 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
20860 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
20870 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
20880 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
20890 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
208a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
208b0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
208c0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
208d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
208e0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
208f0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
20900 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
20910 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
20920 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
20930 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
20940 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
20950 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
20960 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
20970 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
20980 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20990 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
209a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
209b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
209c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
209d0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
209e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
209f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
20a00 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
20a10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
20a20 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
20a30 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
20a40 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
20a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20a60 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
20a70 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
20a80 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
20a90 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
20aa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20ab0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
20ac0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
20ad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20ae0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
20af0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
20b00 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
20b10 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
20b20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
20b30 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
20b40 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
20b50 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
20b60 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
20b70 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
20b80 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
20b90 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
20ba0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
20bb0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
20bc0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
20bd0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
20be0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
20bf0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
20c00 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
20c10 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
20c20 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
20c30 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
20c40 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
20c50 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
20c60 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
20c70 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
20c80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
20c90 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
20ca0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20cb0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
20cc0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
20cd0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
20ce0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
20cf0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
20d00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
20d10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
20d20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
20d30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
20d40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
20d50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
20d60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
20d70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
20d80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
20d90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
20da0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
20db0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
20dc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
20dd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
20de0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
20df0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
20e00 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
20e10 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
20e20 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
20e30 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
20e40 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
20e50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20e60 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
20e70 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
20e80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
20e90 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
20ea0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
20eb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
20ec0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
20ed0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
20ee0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
20ef0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
20f00 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
20f10 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
20f20 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
20f30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
20f40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
20f50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
20f60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
20f70 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
20f80 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
20f90 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
20fa0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
20fb0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
20fc0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
20fd0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
20fe0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
20ff0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
21000 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
21010 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
21020 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
21030 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
21040 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
21050 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
21060 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
21070 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
21080 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
21090 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
210a0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
210b0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
210c0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
210d0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
210e0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
210f0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
21100 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
21110 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
21120 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
21130 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
21140 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
21150 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
21160 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
21170 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
21180 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
21190 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
211a0 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
211b0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
211c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
211d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
211e0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
211f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21200 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
21210 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
21220 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
21230 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
21240 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
21250 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
21260 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
21270 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
21280 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
21290 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
212a0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
212b0 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
212c0 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
212d0 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
212e0 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
212f0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
21300 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
21310 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
21320 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
21330 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
21340 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
21350 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
21360 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
21370 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
21380 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
21390 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
213a0 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
213b0 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
213c0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
213d0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
213e0 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65  .** {H13509} The
213f0 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
21400 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
21410 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
21420 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69  * {H13512} The i
21430 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
21440 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
21450 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
21460 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21470 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
21480 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
21490 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
214a0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
214b0 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
214c0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
214d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
214e0 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
214f0 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
21500 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
21510 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
21520 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68  *.** {H13518} Th
21530 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
21540 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
21550 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
21560 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
21570 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
21580 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
21590 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
215a0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
215b0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
215c0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
215d0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
215e0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
215f0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
21600 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
21610 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
21620 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
21630 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
21640 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
21650 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
21660 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
21670 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21680 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b  * {H13521} The [
21690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
216a0 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
216b0 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
216c0 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
216d0 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
216e0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
216f0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
21700 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
21710 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
21720 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
21730 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
21740 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
21750 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
21760 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eter..**.** {H13
21770 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
21780 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21790 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
217a0 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
217b0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
217c0 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
217d0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
217e0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
217f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
21800 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
21810 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21820 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
21830 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
21840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21850 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
21860 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
21870 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
21880 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
21890 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
218a0 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
218b0 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69  * {H13530} Bindi
218c0 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
218d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
218e0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
218f0 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
21900 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
21910 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
21920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21930 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  S)]..**.** {H135
21940 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
21950 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21960 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
21970 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21980 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
21990 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
219a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
219b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
219c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
219d0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
219e0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
219f0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
21a00 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
21a10 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
21a20 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
21a30 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21a40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d  ..**.** {H13536}
21a50 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21a60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21a70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
21a80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21a90 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
21aa0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
21ab0 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
21ac0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
21ad0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
21ae0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
21af0 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
21b00 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21b10 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61  * {H13539} In ca
21b20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21b30 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
21b40 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
21b50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21b60 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
21b70 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
21b80 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21b90 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
21ba0 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
21bb0 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
21bc0 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
21bd0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
21be0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
21bf0 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
21c00 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
21c10 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
21c20 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
21c30 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
21c40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
21c50 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
21c60 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
21c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d  ..**.** {H13542}
21c80 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
21c90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
21ca0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
21cb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
21cc0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
21cd0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
21ce0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21cf0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
21d00 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
21d10 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
21d20 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
21d30 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
21d40 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
21d50 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
21d60 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
21d70 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
21d80 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
21d90 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  turns..**.** {H1
21da0 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
21db0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21dc0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
21dd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
21de0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21df0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
21e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21e10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21e20 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
21e30 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
21e40 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
21e50 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
21e60 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
21e70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
21e80 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
21e90 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
21ea0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
21eb0 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
21ec0 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ue V..**.** {H13
21ed0 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
21ee0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
21ef0 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
21f00 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
21f10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
21f20 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
21f30 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
21f40 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
21f50 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
21f60 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61  * {H13551} In ca
21f70 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21f80 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
21f90 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
21fa0 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
21fb0 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
21fc0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
21fd0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
21fe0 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
21ff0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
22000 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
22010 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
22020 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
22030 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22040 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
22050 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
22060 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
22070 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
22080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22090 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
220a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
220b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
220c0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
220d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
220e0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
220f0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
22100 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
22110 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
22120 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
22130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22140 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
22150 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
22160 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
22170 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
22180 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22190 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
221a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
221b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
221c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
221d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
221e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
221f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
22200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
22210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22220 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
22230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
22240 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
22250 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
22260 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
22270 20 7b 48 31 33 36 30 30 7d 20 3c 48 31 33 35 30   {H13600} <H1350
22280 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
22290 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
222a0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
222b0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
222c0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
222d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
222e0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
222f0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
22300 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
22310 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
22320 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
22330 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
22340 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
22350 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
22360 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
22370 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
22380 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
22390 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
223a0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
223b0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
223c0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
223d0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
223e0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
223f0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
22400 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
22410 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
22420 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
22430 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
22440 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
22450 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
22460 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
22470 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a  ?NNN are used,.*
22480 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
22490 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
224a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
224b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
224c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
224d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
224e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
224f0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
22500 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
22510 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
22520 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
22530 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30  TS:.**.** {H1360
22540 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
22550 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
22560 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
22570 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
22580 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65         the large
22590 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20  st index of all 
225a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69  SQL parameters i
225b0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
225c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
225d0 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69  ement] S, or 0 i
225e0 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  f S contains no 
225f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
22600 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
22610 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
22620 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
22630 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22640 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
22650 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48  ost Parameter {H
22660 31 33 36 32 30 7d 20 3c 48 31 33 35 30 30 3e 0a  13620} <H13500>.
22670 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
22680 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
22690 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
226a0 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
226b0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
226c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
226d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
226e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
226f0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
22700 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
22710 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
22720 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
22730 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
22740 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
22750 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
22760 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
22770 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
22780 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
22790 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
227a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
227b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
227c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
227d0 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
227e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
227f0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
22800 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
22810 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
22820 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
22830 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d  ed to as "anonym
22840 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
22850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
22860 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
22870 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
22880 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
22890 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
228a0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
228b0 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
228c0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
228d0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
228e0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
228f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
22900 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
22910 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
22920 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
22930 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
22940 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
22950 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
22960 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
22970 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
22980 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22990 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
229a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
229b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
229c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
229d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
229e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
229f0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
22a00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22a10 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
22a20 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
22a30 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d  :.**.** {H13621}
22a40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
22a50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
22a60 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
22a70 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
22a80 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
22a90 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
22aa0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
22ab0 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
22ac0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
22ad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22ae0 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20   S having index 
22af0 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  N, or.**        
22b00 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20    NULL if there 
22b10 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  is no SQL parame
22b20 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
22b30 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   or if the.**   
22b40 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
22b50 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73   with index N is
22b60 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61   an anonymous pa
22b70 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a  rameter "?"..*/.
22b80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22b90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22ba0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
22bb0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
22bc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
22bd0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
22be0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
22bf0 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 48  Name {H13640} <H
22c00 31 33 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  13500>.**.** Ret
22c10 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
22c20 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
22c30 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
22c40 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
22c50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
22c60 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
22c70 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
22c80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
22c90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22ca0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
22cb0 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
22cc0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
22cd0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
22ce0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
22cf0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
22d00 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
22d10 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
22d20 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
22d30 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
22d40 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
22d50 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
22d60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
22d70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
22d80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
22d90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
22da0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
22db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
22dc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
22dd0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
22de0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22df0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
22e00 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
22e10 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20  .**.** {H13641} 
22e20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
22e30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
22e40 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
22e50 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
22e60 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
22e70 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
22e80 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
22e90 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
22ea0 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
22eb0 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
22ec0 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
22ed0 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
22ee0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
22ef0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
22f00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22f10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
22f20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
22f30 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
22f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22f50 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
22f60 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
22f70 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
22f80 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  660}.**.** Contr
22f90 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
22fa0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
22fb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22fc0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
22fd0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
22fe0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
22ff0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
23000 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23010 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
23020 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
23030 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
23040 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
23050 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23060 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b  * {H13661} The [
23070 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23080 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
23090 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
230a0 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
230b0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
230c0 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
230d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
230e0 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
230f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
23100 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
23110 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
23120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
23130 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
23140 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
23150 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
23160 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
23170 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
23180 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
23190 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
231a0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
231b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
231c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
231d0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
231e0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
231f0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
23200 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
23210 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
23220 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
23230 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23240 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65  .** {H13711} The
23250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23260 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
23270 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23280 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
23290 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
232a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
232b0 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
232c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
232d0 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
232e0 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20        or 0 if S 
232f0 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
23300 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  e a result set..
23310 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
23320 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
23330 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23350 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
23360 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
23370 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
23380 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
23390 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
233a0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
233b0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
233c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
233d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
233e0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
233f0 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
23400 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
23410 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
23420 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
23430 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
23440 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
23450 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
23460 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
23470 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
23480 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
23490 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
234a0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
234b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
234c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
234d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
234e0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
234f0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23500 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
23510 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23520 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
23530 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
23540 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
23550 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
23560 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
23570 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
23580 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
23590 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
235a0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
235b0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
235c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
235d0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
235e0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
235f0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
23600 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
23610 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
23620 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
23630 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
23640 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
23650 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
23660 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
23670 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
23680 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
23690 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
236a0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
236b0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
236c0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
236d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
236e0 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
236f0 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
23700 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
23710 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
23720 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
23730 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
23740 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
23750 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
23760 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
23770 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
23780 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
23790 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
237a0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
237b0 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
237c0 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
237d0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
237e0 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {H13721} A succe
237f0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
23800 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
23810 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
23820 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
23830 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23840 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23850 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
23860 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
23870 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
23880 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
23890 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
238a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
238b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
238c0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
238d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
238e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
238f0 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  H13723} A succes
23900 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
23910 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
23920 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
23930 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
23940 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23950 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23960 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
23970 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
23980 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
23990 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
239a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
239b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
239c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
239d0 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
239e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
239f0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  16 string.**    
23a00 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
23a10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
23a20 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54  **.** {H13724} T
23a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23a40 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
23a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23a60 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
23a70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
23a80 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
23a90 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
23aa0 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
23ab0 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
23ac0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
23ad0 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
23ae0 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
23af0 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74  ** {H13725} If t
23b00 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
23b10 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
23b20 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
23b30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
23b40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23b50 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
23b60 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
23b70 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
23b80 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
23b90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
23ba0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20  .**.** {H13726} 
23bb0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
23bc0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
23bd0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
23be0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
23bf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
23c00 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
23c10 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
23c20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
23c30 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
23c40 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
23c50 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
23c60 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
23c70 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
23c80 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
23c90 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
23ca0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37  d..**.** {H13727
23cb0 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
23cc0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
23cd0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
23ce0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
23cf0 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
23d00 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
23d10 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
23d20 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
23d30 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
23d40 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
23d50 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
23d60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
23d70 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
23d80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
23d90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
23da0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23db0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23dc0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
23dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
23de0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
23df0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
23e00 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3740} <S10700>.*
23e10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
23e20 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
23e30 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
23e40 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
23e50 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
23e60 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
23e70 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
23e80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
23e90 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
23ea0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
23eb0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
23ec0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
23ed0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
23ee0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
23ef0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
23f00 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
23f10 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
23f20 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
23f30 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
23f40 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
23f50 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
23f60 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
23f70 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
23f80 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
23f90 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
23fa0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
23fb0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
23fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23fd0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
23fe0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
23ff0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24000 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24010 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
24020 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
24030 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
24040 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
24050 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
24060 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
24070 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
24080 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
24090 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
240a0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
240b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
240c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
240d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
240e0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
240f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24100 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
24110 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
24120 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
24130 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
24140 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
24150 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
24160 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
24170 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
24180 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
24190 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
241a0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
241b0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
241c0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
241d0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
241e0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
241f0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
24200 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
24210 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
24220 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
24230 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
24240 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
24250 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
24260 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
24270 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
24280 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
24290 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
242a0 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
242b0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
242c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
242d0 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
242e0 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
242f0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
24300 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
24310 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
24320 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
24330 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
24340 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
24350 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
24360 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
24370 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
24380 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
24390 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
243a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
243b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
243c0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
243d0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
243e0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
243f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
24400 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
24410 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
24420 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
24430 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24440 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
24450 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
24460 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
24470 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
24480 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
24490 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
244a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
244b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
244c0 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
244d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
244e0 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
244f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24500 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24510 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
24520 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24530 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24540 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
24550 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24560 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24570 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
24580 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24590 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
245a0 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
245b0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
245c0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
245d0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
245e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
245f0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24600 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24610 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
24620 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
24630 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24640 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24650 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
24660 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
24670 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24680 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
24690 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
246a0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
246b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
246c0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
246d0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
246e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
246f0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24700 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
24710 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
24720 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
24730 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24740 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24750 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24760 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24770 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24780 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24790 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
247a0 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
247b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
247c0 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
247d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
247e0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
247f0 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
24800 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24810 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
24820 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
24830 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
24840 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24850 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24860 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
24870 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
24880 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
24890 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
248a0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
248b0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
248c0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
248d0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
248e0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
248f0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24900 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
24910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
24920 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
24930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24940 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24950 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
24960 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
24970 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
24980 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
24990 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
249a0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
249b0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
249c0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
249d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
249e0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
249f0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
24a00 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24a10 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24a20 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24a40 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24a50 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24a60 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
24a70 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
24a80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24a90 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
24aa0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24ab0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
24ac0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
24ad0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
24ae0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
24af0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
24b00 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
24b10 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
24b20 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
24b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24b40 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
24b50 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
24b60 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
24b70 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
24b80 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
24b90 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
24ba0 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
24bb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
24bc0 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
24bd0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
24be0 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
24bf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
24c00 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
24c10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24c20 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24c30 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
24c40 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
24c50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24c60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
24c70 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
24c80 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
24c90 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
24ca0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
24cb0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
24cc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24cd0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
24ce0 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
24cf0 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
24d00 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
24d10 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
24d20 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
24d30 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
24d40 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
24d50 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
24d60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
24d70 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
24d80 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
24d90 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24da0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24db0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
24dc0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
24dd0 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
24de0 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
24df0 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
24e00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24e10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
24e20 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
24e30 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
24e40 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
24e50 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
24e60 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
24e70 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
24e80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
24e90 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
24ea0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
24eb0 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
24ec0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
24ed0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
24ee0 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
24ef0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24f00 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
24f10 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
24f20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
24f30 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
24f40 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
24f50 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
24f60 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
24f70 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
24f80 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
24f90 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
24fa0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
24fb0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
24fc0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24fd0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
24fe0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
24ff0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25000 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25010 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25020 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
25030 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25040 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
25050 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25060 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
25080 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
25090 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
250a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
250b0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
250c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
250d0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
250e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
250f0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
25100 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25110 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
25120 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
25130 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
25140 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
25150 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
25160 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
25170 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
25180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25190 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
251a0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
251b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
251c0 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
251d0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
251e0 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
251f0 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
25200 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
25210 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
25220 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
25230 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
25240 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
25250 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
25260 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
25270 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
25280 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
25290 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
252a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
252b0 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
252c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
252d0 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
252e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
252f0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
25300 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
25310 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
25320 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
25330 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
25340 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
25350 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
25360 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
25370 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
25380 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
25390 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
253a0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
253b0 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
253c0 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
253d0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
253e0 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
253f0 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
25400 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
25410 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
25420 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
25430 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
25440 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
25450 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
25460 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
25470 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
25480 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
25490 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
254a0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
254b0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
254c0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
254d0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
254e0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
254f0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
25500 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
25510 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
25520 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
25530 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
25540 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
25550 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
25560 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
25570 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
25580 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
25590 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
255a0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
255b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
255c0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20  **.** {H13761}  
255d0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
255e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
255f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
25600 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  N)] returns a.**
25610 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d             zero-
25620 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
25630 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
25640 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
25650 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20  datatype.**     
25660 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62        of the tab
25670 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
25680 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74  ppears as the Nt
25690 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
256a0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
256b0 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
256c0 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
256d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
256e0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
256f0 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  H13762}  A succe
25700 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
25720 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
25730 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
25740 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
25750 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
25760 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
25770 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
25780 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
25790 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
257a0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
257b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
257c0 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
257d0 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
257e0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
257f0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
25800 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
25810 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
25820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25830 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
25840 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
25850 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
25860 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
25870 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
25880 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
25890 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
258a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
258b0 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
258c0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68          or if th
258d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
258e0 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  S is an expressi
258f0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72  on or subquery r
25900 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ather.**        
25910 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20     than a table 
25920 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20  column, or if a 
25930 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
25940 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20  n failure.**    
25950 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
25960 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f  ring encoding co
25970 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a  nversions, then.
25980 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c  **           cal
25990 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
259a0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
259b0 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
259c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
259d0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
259e0 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
259f0 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
25a00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25a10 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
25a20 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25a30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25a40 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25a50 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25a60 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
25a70 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
25a80 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
25a90 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
25aa0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
25ab0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25ac0 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
25ad0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
25ae0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
25af0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25b00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
25b10 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
25b20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
25b30 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
25b40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25b50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
25b60 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
25b70 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
25b80 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
25b90 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
25ba0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
25bb0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
25bc0 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
25bd0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
25be0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
25bf0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
25c00 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
25c10 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
25c20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
25c30 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
25c40 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
25c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
25c60 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
25c70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25c80 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
25c90 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
25ca0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
25cb0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
25cc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
25cd0 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
25ce0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
25cf0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
25d00 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
25d10 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
25d20 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
25d30 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
25d40 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
25d50 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
25d60 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
25d70 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
25d80 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
25d90 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
25da0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
25db0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
25dc0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
25dd0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
25de0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
25df0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
25e00 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
25e10 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
25e20 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
25e30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
25e40 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
25e50 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
25e60 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
25e70 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
25e80 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
25e90 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
25ea0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
25eb0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
25ec0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
25ed0 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
25ee0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
25ef0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
25f00 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
25f10 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
25f20 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
25f30 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
25f40 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
25f50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
25f60 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
25f70 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
25f80 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
25f90 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
25fa0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
25fb0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
25fc0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
25fd0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
25fe0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
25ff0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
26000 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
26010 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
26020 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
26030 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26040 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
26050 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
26060 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
26070 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
26080 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
26090 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
260a0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
260b0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
260c0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
260d0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
260e0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
260f0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
26100 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
26110 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
26120 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
26130 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
26140 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
26150 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
26160 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
26170 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
26180 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
26190 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
261a0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
261b0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
261c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
261d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
261e0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
261f0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
26200 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
26210 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
26220 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26230 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
26240 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
26250 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
26260 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
26270 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
26280 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
26290 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
262a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
262b0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
262c0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
262d0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
262e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
262f0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
26300 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
26310 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
26320 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
26330 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
26340 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
26350 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
26360 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
26370 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
26380 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
26390 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
263a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
263b0 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
263c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
263d0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
263e0 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
263f0 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
26400 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
26410 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
26420 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
26430 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
26440 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
26450 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
26460 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
26470 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
26480 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
26490 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
264a0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
264b0 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
264c0 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
264d0 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
264e0 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
264f0 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
26500 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
26510 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
26520 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
26530 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
26540 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
26550 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
26560 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
26570 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
26580 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
26590 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
265a0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
265b0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
265c0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
265d0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
265e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
265f0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
26600 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
26610 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
26620 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
26630 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
26640 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
26650 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
26660 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
26670 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
26680 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26690 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
266a0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
266b0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
266c0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
266d0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
266e0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
266f0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
26700 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
26710 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
26720 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
26730 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
26740 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
26750 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26760 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
26770 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
26780 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
26790 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
267a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
267b0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
267c0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
267d0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
267e0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
267f0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
26800 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
26810 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
26820 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
26830 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
26840 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
26850 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
26860 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
26870 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
26880 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
26890 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
268a0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
268b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
268c0 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20  H13202}  If the 
268d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
268e0 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
268f0 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a  to be run, then.
26900 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
26910 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
26920 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
26930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26940 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
26950 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72     completion or
26960 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61   until it is rea
26970 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f  dy to return ano
26980 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a  ther row of the.
26990 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73  **           res
269a0 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69  ult set, or unti
269b0 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l an [sqlite3_in
269c0 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
269d0 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  upt].**         
269e0 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20    or a run-time 
269f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
26a00 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68  .** {H15304}  Wh
26a10 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
26a20 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
26a30 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
26a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26a50 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f  *           S to
26a60 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
26a70 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  on, the function
26a80 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
26a90 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DONE]..**.** {H
26aa0 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
26ab0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26ac0 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
26ad0 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
26ae0 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  dy to.**        
26af0 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65     return anothe
26b00 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
26b10 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
26b20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
26b30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d  ..**.** {H15308}
26b40 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b    If a call to [
26b50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26b60 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a   encounters an.*
26b70 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
26b80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
26b90 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
26ba0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
26bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
26bc0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
26bd0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
26be0 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
26bf0 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
26c00 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
26c10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
26c20 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
26c30 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20  **.** {H15310}  
26c40 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
26c50 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
26c60 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
26c70 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
26c80 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
26c90 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
26ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
26cc0 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
26cd0 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
26ce0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
26cf0 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
26d00 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
26d10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
26d20 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
26d30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26d40 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  ], then the func
26d50 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
26d60 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
26d70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
26d80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
26d90 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
26da0 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
26db0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
26dc0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
26dd0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
26de0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
26df0 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
26e00 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
26e10 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
26e20 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
26e30 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
26e40 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
26e50 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
26e60 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
26e70 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20  13771}  After a 
26e80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26e90 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72  _step(S)] that r
26ea0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
26eb0 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  OW],.**         
26ec0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    the [sqlite3_d
26ed0 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f  ata_count(S)] ro
26ee0 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
26ef0 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
26f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
26f10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
26f20 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
26f30 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
26f40 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  H13772}  After [
26f50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26f60 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
26f70 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
26f80 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
26f90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
26fa0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
26fb0 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
26fc0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a  n called on the.
26fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
26fe0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26ff0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
27000 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
27010 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
27020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
27030 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
27040 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
27050 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20  reset],.**      
27060 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
27070 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
27080 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27090 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
270a0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
270b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
270c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
270d0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
270e0 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48  tal Datatypes {H
270f0 31 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10265}.** KEYWOR
27100 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
27110 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
27120 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
27130 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
27140 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
27150 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
27160 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
27170 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
27180 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
27190 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
271a0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
271b0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
271c0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
271d0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
271e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
271f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
27200 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
27210 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
27220 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
27230 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
27240 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
27250 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
27260 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
27270 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
27280 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
27290 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
272a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
272b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
272c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
272d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
272e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
272f0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
27300 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
27310 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
27320 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
27330 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
27340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27350 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
27360 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
27370 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
27380 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
27390 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
273a0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
273b0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
273c0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
273d0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
273e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
273f0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
27400 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
27410 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
27420 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
27430 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
27440 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
27450 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
27460 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
27470 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
27480 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27490 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
274a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
274b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
274c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
274d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
274e0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
274f0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
27500 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
27510 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
27520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27530 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
27540 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
27550 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
27560 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
27570 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
27580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
27590 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
275a0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
275b0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
275c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
275d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
275e0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
275f0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
27600 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
27610 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
27620 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
27630 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
27640 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
27650 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
27660 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
27670 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
27680 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
27690 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
276a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
276b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
276c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
276d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
276e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
276f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
27700 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
27710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27720 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
27730 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
27740 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
27750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
27760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
27770 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
27780 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
27790 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
277a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
277b0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
277c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
277d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
277e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
277f0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
27800 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
27810 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
27820 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
27830 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
27840 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27850 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
27860 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27870 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
27880 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
27890 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
278a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
278b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
278c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
278d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
278e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
278f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
27900 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
27910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27920 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
27930 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
27940 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
27950 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
27960 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
27970 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
27980 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
27990 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
279a0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
279b0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
279c0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
279d0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
279e0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
279f0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
27a00 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
27a10 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
27a20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
27a30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
27a40 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
27a50 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
27a60 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
27a70 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
27a80 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
27a90 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
27aa0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
27ab0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
27ac0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27ad0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
27ae0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
27af0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
27b00 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
27b10 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
27b20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
27b30 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
27b40 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
27b50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
27b60 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
27b70 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
27b80 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
27b90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
27ba0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
27bb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
27bc0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
27bd0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
27be0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
27bf0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
27c00 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
27c10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
27c20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
27c30 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
27c40 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
27c50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
27c60 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
27c70 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
27c80 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
27c90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27ca0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
27cb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
27cc0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
27cd0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
27ce0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
27cf0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
27d00 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
27d10 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
27d20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
27d30 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
27d40 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
27d50 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
27d60 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
27d70 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
27d80 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
27d90 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
27da0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
27db0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
27dc0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
27dd0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
27de0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
27df0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
27e00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
27e10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
27e20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
27e30 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
27e40 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
27e50 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
27e60 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
27e70 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
27e80 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
27e90 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
27ea0 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
27eb0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
27ec0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
27ed0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
27ee0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
27ef0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27f00 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
27f10 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
27f20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
27f30 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
27f40 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
27f50 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
27f60 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
27f70 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
27f80 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
27f90 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
27fa0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
27fb0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
27fc0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
27fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
27fe0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
27ff0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
28000 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28010 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
28020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
28030 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
28040 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
28050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
28060 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
28070 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
28080 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
28090 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
280a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
280b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
280c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
280d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
280e0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
280f0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
28100 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
28110 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
28120 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
28130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28140 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
28150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
28160 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
28170 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
28180 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
28190 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
281a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
281b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
281c0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
281d0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
281e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
281f0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
28200 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
28210 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
28220 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
28230 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
28240 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
28250 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
28260 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
28270 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
28280 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
28290 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
282a0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
282b0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
282c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
282d0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
282e0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
282f0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
28300 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
28310 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
28320 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
28330 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
28340 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
28350 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28360 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
28370 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
28380 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
28390 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
283a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
283b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
283c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
283d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
283e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
283f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28400 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
28410 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
28420 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
28430 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
28440 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
28450 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
28460 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
28470 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
28480 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
28490 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
284a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
284b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
284c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
284d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
284e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
284f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
28500 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
28510 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
28520 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
28530 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
28540 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
28550 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
28560 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
28570 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
28580 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
28590 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
285a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
285b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
285c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
285d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
285e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
285f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28600 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
28610 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
28620 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
28630 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28640 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
28650 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
28660 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28670 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
28680 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
28690 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
286a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
286b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
286c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
286d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
286e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
286f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
28700 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
28710 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
28720 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
28730 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
28740 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
28750 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
28760 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
28770 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
28780 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
28790 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
287a0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
287b0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
287c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
287d0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
287e0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
287f0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
28800 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
28810 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
28820 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
28830 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
28840 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
28850 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
28860 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
28870 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
28880 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
28890 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
288a0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
288b0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
288c0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
288d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
288e0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
288f0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
28900 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
28910 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
28920 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
28930 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
28940 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
28950 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
28960 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
28970 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
28980 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
28990 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
289a0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
289b0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
289c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
289d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
289e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
289f0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
28a00 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
28a10 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
28a20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
28a30 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
28a40 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
28a50 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
28a60 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
28a70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28a80 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
28a90 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
28aa0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
28ab0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
28ac0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
28ad0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
28ae0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
28af0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
28b00 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
28b10 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
28b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28b30 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
28b40 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
28b50 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
28b60 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
28b70 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
28b80 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
28b90 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
28ba0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
28bb0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
28bc0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
28bd0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
28be0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
28bf0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
28c00 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
28c10 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
28c20 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
28c30 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
28c40 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
28c50 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
28c60 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
28c70 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
28c80 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
28c90 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
28ca0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
28cb0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
28cc0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
28cd0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
28ce0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
28cf0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
28d00 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
28d10 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
28d20 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
28d30 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
28d40 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
28d50 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
28d60 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
28d70 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
28d80 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
28d90 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
28da0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28db0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
28dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28dd0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
28de0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
28df0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
28e00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28e10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
28e20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
28e30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28e40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
28e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28e60 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
28e70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
28e80 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
28e90 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
28ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
28eb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
28ec0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
28ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28ee0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
28ef0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
28f00 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
28f10 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
28f20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
28f30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
28f40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
28f50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
28f60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
28f70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
28f80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
28f90 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
28fa0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
28fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28fc0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
28fd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
28fe0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
28ff0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
29000 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
29010 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
29020 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
29030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29040 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
29050 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
29060 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
29070 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
29080 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
29090 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
290a0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
290b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
290c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
290d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
290e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
290f0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
29100 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
29110 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
29120 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
29130 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
29140 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
29150 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
29160 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
29170 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
29180 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
29190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
291a0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
291b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
291c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
291d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
291e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
291f0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
29200 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
29210 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
29220 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
29230 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
29240 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
29250 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
29260 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
29270 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
29280 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
29290 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
292a0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
292b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
292c0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
292d0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
292e0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
292f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29300 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {H13803} The [s
29310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29320 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
29330 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
29340 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
29350 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
29360 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29370 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
29380 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
29390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
293a0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c  ent] S into a BL
293b0 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  OB and then retu
293c0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
293d0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
293e0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
293f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d  ..**.** {H13806}
29400 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
29410 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d  lumn_bytes(S,N)]
29420 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29430 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
29440 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
29450 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
29460 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
29470 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
29480 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
29490 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
294a0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
294b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
294c0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
294d0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
294e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
294f0 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  lob(S,N)] or.** 
29500 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
29510 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
29520 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
29530 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
29540 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29550 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
29560 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
29570 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
29580 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
29590 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
295a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
295b0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
295c0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
295d0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
295e0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
295f0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
29600 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
29610 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29620 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16(S,N)]..**.** 
29630 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71  {H13812} The [sq
29640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
29650 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ble(S,N)] interf
29660 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
29670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
29680 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
29690 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
296a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
296b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
296c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
296d0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
296e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
296f0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
29700 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
29710 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
29720 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d  ..**.** {H13815}
29730 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
29740 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
29750 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
29760 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29770 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
29780 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29790 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
297a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
297b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
297c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
297d0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
297e0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
297f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
29800 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
29810 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
29820 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
29830 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
29840 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c  _column_int64(S,
29850 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
29860 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
29870 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
29880 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
29890 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
298a0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
298b0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
298c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
298d0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
298e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
298f0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
29900 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
29910 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
29920 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68  *.** {H13821} Th
29930 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29940 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
29950 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29960 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29970 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
29980 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
29990 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
299a0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
299b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
299c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
299d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
299e0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
299f0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
29a00 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
29a10 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
29a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20  .**.** {H13824} 
29a30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29a40 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
29a50 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
29a60 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
29a70 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
29a80 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
29a90 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
29aa0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
29ab0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
29ac0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
29ad0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
29ae0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
29af0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
29b00 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
29b10 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
29b20 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
29b30 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
29b40 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
29b50 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37  g..**.** {H13827
29b60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29b70 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
29b80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29b90 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
29ba0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
29bb0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
29bc0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
29bd0 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
29be0 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
29bf0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
29c00 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
29c10 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
29c20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
29c30 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29c40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29c50 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
29c60 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
29c70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29c80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d  ..**.** {H13830}
29c90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
29ca0 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
29cb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29cc0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
29cd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
29ce0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29cf0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29d00 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
29d10 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
29d20 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29d30 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29d40 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
29d50 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
29d60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29d70 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
29d80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29d90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
29da0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29db0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29dc0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
29dd0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29de0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29df0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
29e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29e10 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
29e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
29e30 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
29e40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29e50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29e60 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
29e70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
29e80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
29e90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
29ea0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
29eb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
29ec0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
29ed0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29ee0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
29ef0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
29f00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
29f10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29f30 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
29f40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
29f50 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
29f60 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
29f70 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
29f80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
29f90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29fa0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
29fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
29fc0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
29fd0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
29fe0 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
29ff0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a000 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2a010 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2a020 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2a030 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a040 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
2a050 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
2a060 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
2a070 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
2a080 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
2a090 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
2a0a0 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
2a0b0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
2a0c0 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
2a0d0 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
2a0e0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
2a0f0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
2a100 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2a110 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
2a120 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2a130 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2a140 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
2a150 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2a160 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2a170 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
2a180 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
2a190 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2a1a0 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
2a1b0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2a1c0 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
2a1d0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
2a1e0 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
2a1f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
2a200 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
2a210 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
2a220 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
2a230 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
2a240 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
2a250 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
2a260 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
2a270 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
2a280 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
2a290 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
2a2a0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
2a2b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2a2c0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d  :.**.** {H11302}
2a2d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
2a2e0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72  nalize(S)] inter
2a2f0 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68  face destroys th
2a300 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2a310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a320 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65  t] S and release
2a330 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  s all.**        
2a340 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c    memory and fil
2a350 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64  e resources held
2a360 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e   by that object.
2a370 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20  .**.** {H11304} 
2a380 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2a390 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2a3a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2a3b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2a3c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a3d0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2a3e0 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20   an error,.**   
2a3f0 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
2a400 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a410 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73  ] returns that s
2a420 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e  ame error..*/.in
2a430 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2a440 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2a450 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a460 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2a470 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2a480 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2a490 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  330} <S70300>.**
2a4a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2a4b0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2a4c0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2a4d0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2a4e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2a4f0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2a500 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2a510 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2a520 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
2a530 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2a540 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2a550 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2a560 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2a570 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a580 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2a590 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2a5a0 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2a5b0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2a5c0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2a5d0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2a5e0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2a5f0 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b  * {H11332} The [
2a600 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a610 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2a620 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2a630 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2a640 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
2a650 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2a660 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2a670 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49  **.** {H11334} I
2a680 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2a690 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2a6a0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2a6b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a6c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a6d0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2a6e0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2a6f0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2a700 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
2a710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2a720 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2a730 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2a740 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
2a750 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2a760 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2a770 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2a780 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66  *.** {H11336} If
2a790 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2a7a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a7b0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2a7c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2a7d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a7e0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2a7f0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2a800 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2a810 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a820 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2a830 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2a840 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38  ]..**.** {H11338
2a850 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2a860 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2a870 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2a880 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2a890 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
2a8a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2a8b0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2a8c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a8d0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2a8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2a8f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a900 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a910 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2a920 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2a930 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30  Functions {H1610
2a940 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
2a950 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2a960 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2a970 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2a980 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2a990 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a9a0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2a9b0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2a9c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a9d0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2a9e0 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
2a9f0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2aa00 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2aa10 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2aa20 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2aa30 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2aa40 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2aa50 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2aa60 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2aa70 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2aa80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2aa90 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2aaa0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2aab0 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
2aac0 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
2aad0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2aae0 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
2aaf0 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
2ab00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2ab10 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
2ab20 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
2ab30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ab40 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
2ab50 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
2ab60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ab70 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
2ab80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2ab90 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2aba0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2abb0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2abc0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2abd0 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
2abe0 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20   single program 
2abf0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2ac00 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2ac10 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e  onnection intern
2ac20 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66  ally, then SQL f
2ac30 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2ac40 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
2ac50 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64  lly to.** each d
2ac60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ac70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  on..**.** The se
2ac80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2ac90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2aca0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2acb0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
2acc0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54  ** redefined.  T
2acd0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2ace0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2acf0 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
2ad00 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
2ad10 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2ad20 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
2ad30 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
2ad40 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
2ad50 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
2ad60 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
2ad70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2ad80 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2ad90 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2ada0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2adb0 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
2adc0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2add0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2ade0 65 74 65 72 20 69 73 20 74 68 65 20 6e 75 6d 62  eter is the numb
2adf0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ae00 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
2ae10 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2ae20 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20  egate takes. If 
2ae30 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
2ae40 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2ae50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ae60 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2ae70 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
2ae80 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ae90 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ts..**.** The fo
2aea0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
2aeb0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
2aec0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
2aed0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
2aee0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
2aef0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
2af00 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
2af10 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20  arameters.  Any 
2af20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2af30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
2af40 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  ld be able to wo
2af50 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20  rk.** work with 
2af60 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2af70 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2af80 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2af90 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2afa0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2afb0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2afc0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2afd0 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20    It is allowed 
2afe0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
2aff0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b000 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
2b010 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b020 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
2b030 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
2b040 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
2b050 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2b060 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
2b070 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75  tRep..** When mu
2b080 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2b090 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2b0a0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
2b0b0 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
2b0c0 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
2b0d0 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
2b0e0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
2b0f0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
2b100 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
2b110 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
2b120 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
2b130 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
2b140 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
2b150 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
2b160 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
2b170 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2b180 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
2b190 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
2b1a0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
2b1b0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
2b1c0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
2b1d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b1e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
2b1f0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
2b200 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
2b210 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
2b220 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
2b230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e  .**.** The seven
2b240 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e  th, eighth and n
2b250 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c  inth parameters,
2b260 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e   xFunc, xStep an
2b270 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a  d xFinal, are.**
2b280 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c   pointers to C-l
2b290 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e  anguage function
2b2a0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2b2b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2b2c0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b2d0 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20  e. A scalar SQL 
2b2e0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2b2f0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2b300 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2b310 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2b320 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y, NULL pointers
2b330 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
2b340 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
2b350 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
2b360 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72  ameters. An aggr
2b370 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2b380 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2b390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b3a0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46   xStep.** and xF
2b3b0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68  inal and NULL sh
2b3c0 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 66  ould be passed f
2b3d0 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c  or xFunc. To del
2b3e0 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2b3f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2b400 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2b410 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20  ss NULL for all 
2b420 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63  three function c
2b430 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2b440 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2b450 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2b460 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2b470 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2b480 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2b490 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2b4a0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2b4b0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2b4c0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2b4d0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2b4e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2b4f0 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74  ncodings.  SQLit
2b500 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2b510 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b520 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2b530 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2b540 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2b550 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2b560 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
2b570 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
2b580 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
2b590 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b5a0 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  n16()] interface
2b5b0 20 62 65 68 61 76 65 73 20 65 78 61 63 74 6c 79   behaves exactly
2b5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69 6b  .**          lik
2b5d0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2b5e0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e  e_function()] in
2b5f0 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
2b600 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
2b610 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
2b620 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61   the zFunctionNa
2b630 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a  me argument as z
2b640 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2b650 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
2b660 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72    native byte or
2b670 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  der instead of a
2b680 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2b690 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  d UTF-8..**.** {
2b6a0 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73  H16106} A succes
2b6b0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
2b6c0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
2b6d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2b6e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2b6f0 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  N,E,...)] interf
2b700 61 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a  ace registers.**
2b710 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
2b720 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
2b730 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20  unctions in the 
2b740 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b750 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
2b760 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c      used to impl
2b770 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2b780 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77  nction named X w
2b790 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73  ith N parameters
2b7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2b7b0 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72   having a prefer
2b7c0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2b7d0 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g of E..**.** {H
2b7e0 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73  16109} A success
2b7f0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2b800 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b810 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2b820 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2b830 20 20 20 72 65 70 6c 61 63 65 73 20 74 68 65 20     replaces the 
2b840 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
2b850 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
2b860 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
2b870 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2b880 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
2b890 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
2b8a0 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b  * {H16112} The [
2b8b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b8c0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
2b8d0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2b8e0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2b8f0 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f 64 65     a return code
2b900 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2b910 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20 66 75  R] if the SQL fu
2b920 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
2b930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
2b940 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
2b950 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
2b960 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2b970 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  tor..**.** {H161
2b980 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d 75 73  18} Either F mus
2b990 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20  t be NULL and S 
2b9a0 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2b9b0 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20  LL or else F.** 
2b9c0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
2b9d0 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2b9e0 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72   are NULL, other
2b9f0 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  wise.**         
2ba00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ba10 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ba20 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75  E,P,F,S,L)] retu
2ba30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  rns [SQLITE_ERRO
2ba40 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32  R]..**.** {H1612
2ba50 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2ba60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ba70 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
2ba80 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  e fails with an.
2ba90 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
2baa0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2bab0 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65  E_BUSY] if there
2bac0 20 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64   exist [prepared
2bad0 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20   statements].** 
2bae0 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
2baf0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2bb00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bb10 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  n] D..**.** {H16
2bb20 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2bb30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2bb40 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e  n(D,X,N,...)] in
2bb50 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
2bb60 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
2bb70 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20    error code of 
2bb80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2bb90 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 28 73  f parameter N (s
2bba0 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 6e 75  pecifying the nu
2bbb0 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
2bbc0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
2bbd0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bbe0 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74 65 72  n being register
2bbf0 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20  ed) is less.**  
2bc00 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20          than -1 
2bc10 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2bc20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  127..**.** {H161
2bc30 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f  27} When N is no
2bc40 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  n-negative, the 
2bc50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bc60 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2bc70 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2bc80 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2bc90 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  s callbacks to b
2bca0 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2bcb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a  e SQL function.*
2bcc0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2bcd0 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2bce0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2bcf0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2bd00 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2bd10 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2bd20 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65  .** {H16130} Whe
2bd30 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2bd40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bd50 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2bd60 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2bd70 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2bd80 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2bd90 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2bda0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2bdb0 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20            named 
2bdc0 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65  X with any numbe
2bdd0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2bde0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57  **.** {H16133} W
2bdf0 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2be00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2be10 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2be20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
2be30 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
2be40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2be50 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2be60 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20  ion X.**        
2be70 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69    and when one i
2be80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
2be90 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f  s N>=0 and the o
2bea0 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a  ther has N=(-1).
2beb0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2bec0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2bed0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e  ith a non-zero N
2bee0 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2bef0 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68  *.** {H16136} Wh
2bf00 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2bf10 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bf20 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2bf30 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2bf40 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2bf50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2bf60 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2bf70 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20  tion X with.**  
2bf80 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2bf90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2bfa0 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20  ents N but with 
2bfb0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20  different.**    
2bfc0 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20        encodings 
2bfd0 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c  E, then the impl
2bfe0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65  ementation where
2bff0 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a   E matches the.*
2c000 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2c010 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
2c020 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
2c030 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e   {H16139} For an
2c040 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2c050 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20  unction created 
2c060 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
2c070 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2c080 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2c090 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65  ,E,P,0,S,L)] the
2c0a0 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20   finalizer.**   
2c0b0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2c0c0 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 62 65  L will always be
2c0d0 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
2c0e0 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
2c0f0 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
2c100 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
2c110 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2c120 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  imes..**.** {H16
2c130 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
2c140 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
2c150 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
2c160 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
2c170 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
2c180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c190 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
2c1a0 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
2c1b0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2c1c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
2c1d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
2c1e0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2c1f0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
2c200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2c210 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
2c220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c230 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
2c240 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c250 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2c260 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70 72 6f   are always [pro
2c270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c280 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2c290 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2c2a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2c2b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2c2c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2c2d0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2c2e0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2c2f0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2c300 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2c310 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2c320 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c330 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c340 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2c350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c360 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c370 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2c380 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2c390 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2c3a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c3b0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2c3c0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2c3d0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2c3e0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2c3f0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2c400 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2c410 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2c420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2c430 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2c440 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2c450 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2c460 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c470 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c480 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2c490 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2c4a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c4b0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2c4c0 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
2c4d0 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
2c4e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2c4f0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2c500 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2c510 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2c520 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2c530 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2c540 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2c550 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2c560 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2c570 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c580 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2c590 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c5a0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2c5b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2c5c0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2c5d0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2c5e0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2c5f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2c600 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2c610 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c620 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2c630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c640 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2c650 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2c660 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2c670 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2c680 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
2c690 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
2c6a0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2c6b0 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
2c6c0 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
2c6d0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2c6e0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2c6f0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2c700 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
2c710 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
2c720 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
2c730 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
2c740 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
2c750 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
2c760 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2c770 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2c780 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2c790 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2c7a0 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2c7b0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2c7c0 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2c7d0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
2c7e0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
2c7f0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2c800 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2c810 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
2c820 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2c830 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2c840 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
2c850 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2c860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2c870 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
2c880 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2c890 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2c8a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
2c8b0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2c8c0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
2c8d0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2c8e0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2c8f0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2c900 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2c910 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2c920 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2c930 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2c940 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31  meter Values {H1
2c950 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5100} <S20200>.*
2c960 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2c970 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2c980 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2c990 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2c9a0 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2c9b0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2c9c0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2c9d0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2c9e0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2c9f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2ca00 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2ca10 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2ca20 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2ca30 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2ca40 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2ca50 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2ca60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ca70 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2ca80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ca90 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2caa0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2cab0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2cac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2cad0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2cae0 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2caf0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2cb00 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2cb10 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2cb20 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2cb30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cb40 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2cb50 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2cb60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2cb70 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2cb80 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2cb90 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2cba0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2cbb0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2cbc0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2cbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2cbe0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2cbf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2cc00 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2cc10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cc20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2cc30 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2cc40 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2cc50 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2cc60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cc70 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2cc80 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2cc90 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2cca0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2ccb0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
2ccc0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
2ccd0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
2cce0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
2ccf0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
2cd00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
2cd10 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
2cd20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cd30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
2cd40 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
2cd50 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
2cd60 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
2cd70 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
2cd80 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
2cd90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2cda0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2cdb0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2cdc0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2cdd0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2cde0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2cdf0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2ce00 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2ce10 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2ce20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2ce30 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2ce40 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2ce50 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
2ce60 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2ce70 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2ce80 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2ce90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2cea0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2ceb0 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2cec0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2ced0 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2cee0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2cef0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2cf00 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2cf10 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2cf20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2cf30 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2cf40 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2cf50 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2cf60 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2cf70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2cf80 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2cf90 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2cfa0 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2cfb0 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2cfc0 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2cfd0 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2cfe0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2cff0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2d000 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2d010 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2d020 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2d030 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2d040 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2d050 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2d060 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2d070 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2d080 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2d090 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2d0a0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2d0b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2d0c0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2d0d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d0e0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2d0f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d100 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2d110 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2d120 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2d130 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2d140 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2d150 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d160 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2d170 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2d180 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2d190 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2d1a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d1b0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2d1c0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2d1d0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2d1e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2d1f0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2d200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2d210 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
2d220 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2d230 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54  **.** {H15103} T
2d240 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d250 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2d260 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d270 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d280 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d290 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d2a0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2d2b0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2d2c0 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e    returns a poin
2d2d0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2d2e0 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2d2f0 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b  * {H15106} The [
2d300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2d310 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2d320 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2d330 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2d340 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d350 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2d360 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2d370 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2d380 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2d390 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2d3a0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2d3b0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2d3c0 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2d3d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2d3e0 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2d3f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d400 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d410 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  (V)]..**.** {H15
2d420 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2d430 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2d440 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2d450 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2d460 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2d470 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2d480 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2d490 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d4a0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2d4b0 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2d4c0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d4d0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2d4e0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2d4f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d500 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2d510 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2d520 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d530 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
2d540 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d550 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2d560 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65  .** {H15112} The
2d570 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d580 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2d590 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2d5a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d5b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d5c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2d5d0 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2d5e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2d5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2d600 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2d610 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2d620 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {H15115} The [s
2d630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d640 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2d650 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2d660 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2d670 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d680 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2d690 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2d6a0 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2d6b0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2d6c0 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2d6d0 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2d6e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38  r..**.** {H15118
2d6f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d700 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2d710 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d720 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d730 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d740 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d750 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2d760 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2d770 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2d780 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2d790 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2d7a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d  ..**.** {H15121}
2d7b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d7c0 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2d7d0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2d7e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d7f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d800 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d810 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2d820 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2d830 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2d840 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2d850 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2d860 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2d870 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H15124} The [sql
2d880 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d890 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2d8a0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2d8b0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2d8c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d8d0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2d8e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2d8f0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2d900 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2d910 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2d920 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2d930 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2d940 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d950 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2d960 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54  **.** {H15127} T
2d970 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d980 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
2d990 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d9a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d9b0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d9c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d9d0 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2d9e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2d9f0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2da00 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
2da10 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
2da20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2da30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2da40 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2da50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d  ..**.** {H15130}
2da60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2da70 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2da80 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2da90 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2daa0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2dab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2dac0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2dad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2dae0 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2daf0 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2db00 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2db10 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2db20 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2db30 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2db40 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2db50 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
2db60 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
2db70 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2db80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2db90 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2dba0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2dbb0 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2dbc0 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2dbd0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2dbe0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2dbf0 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2dc00 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2dc10 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2dc20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
2dc30 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20  .**.** {H15136} 
2dc40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2dc50 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2dc60 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2dc70 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
2dc80 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
2dc90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2dca0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
2dcb0 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
2dcc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2dcd0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2dce0 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
2dcf0 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
2dd00 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
2dd10 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
2dd20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
2dd30 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2dd40 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2dd50 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2dd60 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2dd70 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2dd80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
2dd90 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2dda0 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
2ddb0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ddc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ddd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2dde0 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
2ddf0 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
2de00 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2de10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2de20 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
2de30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2de40 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2de50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2de60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2de70 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2de80 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
2de90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2dea0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2deb0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2dec0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2ded0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
2dee0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2def0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2df00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2df10 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2df20 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2df30 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2df40 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2df50 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2df60 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2df70 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2df80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2df90 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2dfa0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2dfb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2dfc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2dfd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2dfe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2dff0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2e000 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2e010 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2e020 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2e030 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2e040 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2e050 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2e060 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
2e070 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
2e080 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
2e090 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
2e0a0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2e0b0 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
2e0c0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
2e0d0 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
2e0e0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2e0f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
2e100 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
2e110 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e120 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
2e130 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
2e140 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
2e150 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
2e160 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
2e170 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
2e180 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
2e190 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
2e1a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2e1b0 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
2e1c0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2e1d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2e1e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e1f0 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
2e200 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2e210 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
2e220 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2e230 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2e240 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e250 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
2e260 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
2e270 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
2e280 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
2e290 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
2e2a0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2e2b0 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
2e2c0 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
2e2d0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
2e2e0 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
2e2f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
2e300 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
2e310 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
2e320 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
2e330 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
2e340 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
2e350 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
2e360 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
2e370 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2e380 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
2e390 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
2e3a0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
2e3b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e3c0 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2e3d0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e3e0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e3f0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2e400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2e410 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2e420 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2e430 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20  ** {H16211} The 
2e440 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
2e450 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   of [sqlite3_agg
2e460 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2e470 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ,N)] for.**     
2e480 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61       a particula
2e490 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e  r instance of an
2e4a0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2e4b0 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69  ion (for a parti
2e4c0 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20  cular.**        
2e4d0 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75    context C) cau
2e4e0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c  ses SQLite to al
2e4f0 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f  locate N bytes o
2e500 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20  f memory,.**    
2e510 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20        zero that 
2e520 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2e530 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  rn a pointer to 
2e540 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65  the allocated me
2e550 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  mory..**.** {H16
2e560 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79  213} If a memory
2e570 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2e580 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a  r occurs during.
2e590 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2e5a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2e5b0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65  ontext(C,N)] the
2e5c0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  n the function r
2e5d0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20  eturns 0..**.** 
2e5e0 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20  {H16215} Second 
2e5f0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69  and subsequent i
2e600 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a  nvocations of.**
2e610 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e620 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e630 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74  text(C,N)] for t
2e640 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20  he same context 
2e650 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20  pointer C.**    
2e660 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65        ignore the
2e670 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64   N parameter and
2e680 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
2e690 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a  r to the same.**
2e6a0 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20            block 
2e6b0 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  of memory return
2e6c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2e6d0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2e6e0 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d  * {H16217} The m
2e6f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
2e700 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  by [sqlite3_aggr
2e710 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2e720 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  N)] is.**       
2e730 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79     automatically
2e740 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65   freed on the ne
2e750 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  xt call to [sqli
2e760 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2e770 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2e780 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2e790 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2e7a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f  ed statement] co
2e7b0 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  ntaining.**     
2e7c0 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61       the aggrega
2e7d0 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  te function asso
2e7e0 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74  ciated with cont
2e7f0 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ext C..*/.void *
2e800 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2e810 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2e820 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2e830 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2e840 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2e850 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2e860 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32  s {H16240} <S202
2e870 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2e880 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2e890 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e8a0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2e8b0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2e8c0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2e8d0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2e8e0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2e8f0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2e900 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e910 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2e920 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e930 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2e940 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2e950 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2e960 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2e970 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2e980 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  tion. {END}.**.*
2e990 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2e9a0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2e9b0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2e9c0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2e9d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2e9e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2e9f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2ea00 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2ea10 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65  .** {H16243} The
2ea20 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2ea30 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ata(C)] interfac
2ea40 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2ea50 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2ea60 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72      P pointer fr
2ea70 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
2ea80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ea90 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eaa0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2eab0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eac0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c  _function16(D,X,
2ead0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61  N,E,P,F,S,L)] ca
2eae0 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  ll that.**      
2eaf0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
2eb00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2eb10 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2eb20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2eb30 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ] C..*/.void *sq
2eb40 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2eb50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2eb60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2eb70 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2eb80 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2eb90 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 0a 2a  tions {H16250}.*
2eba0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ebb0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2ebc0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
2ebd0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2ebe0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2ebf0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
2ec00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
2ec10 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
2ec20 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2ec30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ec40 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2ec50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ec60 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2ec70 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2ec80 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2ec90 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2eca0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2ecb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
2ecc0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2ecd0 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6253} The [sqlit
2ece0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2ecf0 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61  ndle(C)] interfa
2ed00 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2ed10 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
2ed20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66       D pointer f
2ed30 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2ed40 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ed50 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2ed60 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
2ed70 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2ed80 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
2ed90 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
2eda0 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
2edb0 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
2edc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2edd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ede0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2edf0 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
2ee00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
2ee10 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
2ee20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2ee30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ee40 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
2ee50 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
2ee60 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
2ee70 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2ee80 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2ee90 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2eea0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2eeb0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2eec0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2eed0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2eee0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2eef0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2ef00 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2ef10 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2ef20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2ef30 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2ef40 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2ef50 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2ef60 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2ef70 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2ef80 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2ef90 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2efa0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2efb0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2efc0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2efd0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2efe0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2eff0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2f000 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2f010 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2f020 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2f030 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f040 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2f050 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2f060 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2f070 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2f080 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2f090 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2f0a0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2f0b0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2f0c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2f0d0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2f0e0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2f0f0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2f100 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2f110 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2f120 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2f130 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
2f140 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f150 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2f160 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2f170 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
2f180 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
2f190 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
2f1a0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
2f1b0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
2f1c0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
2f1d0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
2f1e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f1f0 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
2f200 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
2f210 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
2f220 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
2f230 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
2f240 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
2f250 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
2f260 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
2f270 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
2f280 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
2f290 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
2f2a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
2f2b0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
2f2c0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2f2d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2f2e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2f2f0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
2f300 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
2f310 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
2f320 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
2f330 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
2f340 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
2f350 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
2f360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f370 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f380 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
2f390 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2f3a0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2f3b0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
2f3c0 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
2f3d0 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
2f3e0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
2f3f0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
2f400 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2f410 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2f420 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
2f430 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
2f440 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f450 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2f460 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
2f470 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
2f480 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
2f490 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
2f4a0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
2f4b0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2f4c0 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
2f4d0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
2f4e0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
2f4f0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
2f500 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
2f510 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
2f520 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
2f530 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
2f540 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
2f550 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
2f560 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
2f570 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
2f580 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
2f590 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
2f5a0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
2f5b0 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
2f5c0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2f5d0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2f5e0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2f5f0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2f600 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2f610 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2f620 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2f630 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2f640 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
2f650 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
2f660 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2f670 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2f680 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2f690 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2f6a0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f6b0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
2f6c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2f6d0 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65  .** {H16272} The
2f6e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2f6f0 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
2f700 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f710 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
2f720 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
2f730 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f740 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
2f750 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
2f760 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2f770 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
2f780 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
2f790 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
2f7a0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
2f7b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
2f7c0 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
2f7d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d  ..**.** {H16274}
2f7e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
2f7f0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2f800 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
2f810 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
2f820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
2f830 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
2f840 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
2f850 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f860 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
2f870 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53  **.** {H16276} S
2f880 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2f890 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2f8a0 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2f8b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
2f8c0 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
2f8d0 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
2f8e0 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
2f8f0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
2f900 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
2f910 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
2f920 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
2f930 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
2f940 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f950 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
2f960 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {H16277} SQLite 
2f970 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
2f980 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
2f990 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
2f9a0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
2f9b0 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
2f9c0 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
2f9d0 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
2f9e0 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20  * {H16278} When 
2f9f0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2fa00 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
2fa10 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
2fa20 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
2fa30 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
2fa40 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
2fa50 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2fa60 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
2fa70 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2fa80 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
2fa90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
2faa0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53  **.** {H16279} S
2fab0 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
2fac0 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
2fad0 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
2fae0 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
2faf0 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
2fb00 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
2fb10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
2fb20 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
2fb30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2fb40 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
2fb50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2fb60 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
2fb70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2fb80 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2fb90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2fba0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2fbb0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2fbc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2fbd0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2fbe0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2fbf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fc00 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2fc10 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2fc20 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
2fc30 7b 48 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {H10280}.**.** T
2fc40 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2fc50 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
2fc60 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
2fc70 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
2fc80 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
2fc90 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
2fca0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2fcb0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
2fcc0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
2fcd0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2fce0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2fcf0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2fd00 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2fd10 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2fd20 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2fd30 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2fd40 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2fd50 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
2fd60 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2fd70 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2fd80 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2fd90 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2fda0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2fdb0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2fdc0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2fdd0 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2fde0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2fdf0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2fe00 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2fe10 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2fe20 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2fe30 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2fe40 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2fe50 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2fe60 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2fe70 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2fe80 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2fe90 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2fea0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2feb0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2fec0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2fed0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2fee0 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2fef0 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2ff00 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2ff10 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2ff20 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2ff30 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2ff40 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2ff50 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
2ff60 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
2ff70 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2ff80 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
2ff90 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2ffa0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
2ffb0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
2ffc0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2ffd0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
2ffe0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fff0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30000 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30010 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
30020 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30030 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
30040 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
30050 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
30060 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
30070 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
30080 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
30090 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
300a0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
300b0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
300c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
300d0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
300e0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
300f0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
30100 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
30110 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
30120 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30130 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
30140 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
30150 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
30160 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30170 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30180 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
30190 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
301a0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
301b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
301c0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
301d0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
301e0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
301f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
30200 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30210 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
30220 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
30230 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
30240 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
30250 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30260 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
30270 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
30280 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
30290 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
302a0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
302b0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
302c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
302d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
302e0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
302f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
30300 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
30310 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
30320 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30330 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
30340 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
30350 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
30360 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
30370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
30390 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
303a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
303b0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
303c0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
303d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
303e0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
303f0 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
30400 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
30410 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
30420 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
30430 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
30440 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
30450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30460 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
30470 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
30480 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
30490 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
304a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
304b0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
304c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
304d0 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
304e0 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
304f0 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
30500 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
30510 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
30520 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
30530 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
30540 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
30550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30570 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
30580 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30590 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
305a0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
305b0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
305c0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
305d0 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
305e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
305f0 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
30600 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
30610 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
30620 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
30630 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
30640 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
30650 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
30660 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
30670 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
30680 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
30690 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
306a0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
306b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
306c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
306d0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
306e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
306f0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
30700 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
30710 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
30720 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
30730 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
30740 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
30750 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
30760 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
30770 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
30780 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
30790 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
307a0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
307b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
307c0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
307d0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
307e0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
307f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
30800 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
30810 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
30820 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
30830 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
30840 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
30850 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
30860 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
30870 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
30880 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
30890 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
308a0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
308b0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
308c0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
308d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
308e0 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
308f0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
30900 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
30910 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
30920 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
30930 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
30940 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
30950 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
30960 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30970 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
30980 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
30990 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
309a0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
309b0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
309c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
309d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
309e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
309f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30a00 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
30a10 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
30a20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30a30 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
30a40 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
30a50 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
30a60 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
30a70 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
30a80 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30a90 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
30aa0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
30ab0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
30ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
30ad0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
30ae0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
30af0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30b00 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
30b10 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
30b20 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
30b30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
30b40 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
30b50 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
30b60 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
30b70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30b80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30b90 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
30ba0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30bb0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
30bc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
30bd0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
30be0 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
30bf0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
30c00 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
30c10 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
30c20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
30c30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
30c40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30c50 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
30c60 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
30c70 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
30c80 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
30c90 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
30ca0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
30cb0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
30cc0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
30cd0 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
30ce0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
30cf0 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
30d00 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
30d10 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
30d20 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
30d30 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
30d40 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30d50 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
30d60 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
30d70 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
30d80 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
30d90 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
30da0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
30db0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
30dc0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
30dd0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
30de0 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
30df0 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
30e00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
30e10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30e30 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
30e40 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
30e50 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
30e60 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
30e70 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
30e80 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
30e90 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
30ea0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
30eb0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
30ec0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
30ed0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
30ee0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
30ef0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
30f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30f10 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
30f20 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
30f30 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
30f40 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
30f50 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
30f60 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
30f70 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
30f80 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
30f90 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
30fa0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
30fb0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
30fc0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
30fd0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
30fe0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
30ff0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31000 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
31010 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31020 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
31030 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
31040 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
31050 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
31060 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
31070 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
31080 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
31090 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
310a0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
310b0 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
310c0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
310d0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
310e0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
310f0 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
31100 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31110 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31120 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31130 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31140 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31150 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
31160 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
31170 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
31180 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31190 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
311a0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
311b0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
311c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
311d0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
311e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
311f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
31200 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31210 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
31220 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
31230 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31240 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
31250 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
31260 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31270 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
31280 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
31290 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
312a0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
312b0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
312c0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
312d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
312e0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
312f0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
31300 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
31310 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
31320 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
31330 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
31340 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
31350 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
31360 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
31370 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
31380 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31390 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
313a0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
313b0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
313c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
313d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
313e0 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
313f0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
31400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31410 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
31420 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
31430 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
31440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
31450 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
31460 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
31470 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
31480 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
31490 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
314a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
314b0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
314c0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
314d0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
314e0 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
314f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
31500 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
31510 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33  S:.**.** {H16403
31520 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65  } The default re
31530 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
31540 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  any SQL function
31550 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
31560 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71  {H16406} The [sq
31570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31580 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  b(C,V,N,D)] inte
31590 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
315a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
315b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
315c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
315d0 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20   BLOB that is N 
315e0 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
315f0 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20    in length and 
31600 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69  with content poi
31610 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a  nted to by V..**
31620 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65  .** {H16409} The
31630 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31640 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e  _double(C,V)] in
31650 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31660 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31670 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31680 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31690 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
316a0 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  int value V..**.
316b0 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20  ** {H16412} The 
316c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
316d0 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e  error(C,V,N)] in
316e0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
316f0 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
31700 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
31710 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31720 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
31730 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
31740 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
31750 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
31760 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61  TF-8 error messa
31770 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56  ge copied from V
31780 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20   up to the.**   
31790 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72         first zer
317a0 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20  o byte or until 
317b0 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
317c0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
317d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35  e..**.** {H16415
317e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
317f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c  esult_error16(C,
31800 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
31810 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
31820 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
31830 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
31840 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
31850 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
31860 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
31870 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
31880 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61   and a UTF-16 na
31890 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
318a0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
318b0 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
318c0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
318d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
318e0 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
318f0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
31900 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
31910 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
31920 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54  **.** {H16418} T
31930 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31940 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
31950 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
31960 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
31970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
31980 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
31990 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
319a0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
319b0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
319c0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
319d0 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
319e0 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
319f0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
31a00 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
31a10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
31a20 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
31a30 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
31a40 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
31a50 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
31a60 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31a70 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
31a80 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
31a90 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
31aa0 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
31ab0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
31ac0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
31ad0 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {H16424} The [sq
31ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31af0 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
31b00 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31b10 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
31b20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
31b30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
31b40 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
31b50 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
31b60 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
31b70 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
31b80 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
31b90 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nged..**.** {H16
31ba0 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
31bb0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
31bc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
31bd0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
31be0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
31bf0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
31c00 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
31c10 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
31c20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d  ..**.** {H16430}
31c30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31c40 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
31c50 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31c60 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31c70 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31c80 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31c90 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
31ca0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
31cb0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54  **.** {H16433} T
31cc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31cd0 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
31ce0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31cf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31d00 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
31d10 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
31d20 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
31d30 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
31d40 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
31d50 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
31d60 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
31d70 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
31d80 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31d90 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
31da0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  F-8 string.**   
31db0 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
31dc0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
31dd0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
31de0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
31df0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
31e00 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
31e10 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
31e20 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {H16439} The [s
31e30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31e40 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
31e50 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31e60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31e70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31e80 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31e90 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74  e the UTF-16 nat
31ea0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
31eb0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
31ec0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
31ed0 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
31ee0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
31ef0 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
31f00 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
31f10 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
31f20 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
31f30 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  442} The [sqlite
31f40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
31f50 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
31f60 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31f70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31f80 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
31f90 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
31fa0 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  he UTF-16 big-en
31fb0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
31fc0 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
31fd0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
31fe0 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
31ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
32000 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
32010 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
32020 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
32030 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b  * {H16445} The [
32040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32050 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
32060 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32070 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32080 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32090 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
320a0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
320b0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
320c0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
320d0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
320e0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
320f0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
32100 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
32110 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
32120 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
32130 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
32140 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
32150 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
32160 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
32170 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
32180 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
32190 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
321a0 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72   to be the [unpr
321b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
321c0 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
321d0 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
321e0 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20  ** {H16451} The 
321f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32200 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
32210 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32220 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32230 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
32240 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32250 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42  e an N-byte BLOB
32260 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
32270 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68  *.** {H16454} Th
32280 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32290 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
322a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
322b0 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
322c0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
322d0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
322e0 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
322f0 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
32300 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
32310 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
32320 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {H16457} If the 
32330 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
32340 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
32350 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
32360 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
32370 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
32380 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
32390 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
323a0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
323b0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
323c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
323d0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
323e0 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
323f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32400 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
32410 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
32420 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
32430 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
32440 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
32450 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
32460 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
32470 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
32480 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
32490 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
324a0 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
324b0 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74  ** {H16460} If t
324c0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
324d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
324e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
324f0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
32500 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32510 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
32520 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
32530 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
32540 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32550 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32560 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32570 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
32580 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32590 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
325a0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
325b0 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
325c0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
325d0 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
325e0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
325f0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
32600 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32610 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
32620 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
32630 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33  y..**.** {H16463
32640 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
32650 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
32660 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
32670 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
32680 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
32690 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
326a0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
326b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
326c0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
326d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
326e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
326f0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
32700 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
32710 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32720 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
32730 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
32740 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
32750 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
32760 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
32770 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
32780 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
32790 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
327a0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
327b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
327c0 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
327d0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
327e0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
327f0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
32800 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
32810 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
32820 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
32830 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32840 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32850 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
32860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32870 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
32880 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
32890 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
328a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
328b0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
328c0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
328d0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
328e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
328f0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
32900 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
32910 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
32920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32930 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
32940 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32960 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
32970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32980 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32990 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
329a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
329b0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
329c0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
329d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
329e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
329f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
32a00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32a10 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
32a20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32a30 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
32a40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
32a50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32a60 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
32a70 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
32a80 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
32a90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32ab0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
32ac0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32ad0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
32ae0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32af0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32b00 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32b10 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32b20 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
32b30 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
32b40 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32b50 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
32b60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32b70 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
32b80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
32b90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32ba0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
32bb0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
32bc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
32bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
32be0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
32bf0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
32c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32c10 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
32c20 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
32c30 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
32c40 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
32c50 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
32c60 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
32c70 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32c80 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
32c90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32ca0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
32cb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32cc0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
32cd0 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
32ce0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
32cf0 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
32d00 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
32d10 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
32d20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
32d30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
32d40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32d50 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
32d60 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
32d70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32d80 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
32d90 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
32da0 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
32db0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
32dc0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
32dd0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
32de0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
32df0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
32e00 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
32e10 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
32e20 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
32e30 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
32e40 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
32e50 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
32e60 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
32e70 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
32e80 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
32e90 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
32ea0 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
32eb0 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c  6 little-endian,
32ec0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
32ed0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
32ee0 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
32ef0 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
32f00 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
32f10 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
32f20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
32f30 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
32f40 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
32f50 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
32f60 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
32f70 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
32f80 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
32f90 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
32fa0 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
32fb0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
32fc0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
32fd0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
32fe0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
32ff0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
33000 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
33010 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
33020 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
33030 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
33040 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
33050 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
33060 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
33070 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
33080 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
33090 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
330a0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
330b0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
330c0 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
330d0 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
330e0 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
330f0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
33100 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
33110 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33120 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
33130 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33140 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
33150 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
33160 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
33170 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
33180 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
33190 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
331a0 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
331b0 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
331c0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
331d0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
331e0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
331f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
33200 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
33210 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
33220 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
33230 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
33240 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
33250 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
33260 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
33270 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
33280 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
33290 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
332a0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
332b0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
332c0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
332d0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
332e0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
332f0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
33300 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
33310 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33320 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
33330 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
33340 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33350 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
33360 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
33370 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
33380 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
33390 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
333a0 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
333b0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
333c0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
333d0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
333e0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
333f0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
33400 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
33410 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
33420 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
33430 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33440 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
33450 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
33460 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
33470 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
33480 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
33490 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
334a0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
334b0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
334c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
334d0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
334e0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
334f0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
33500 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
33510 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20  *.** {H16603} A 
33520 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
33530 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
33540 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
33550 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33560 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
33570 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
33580 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
33590 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
335a0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
335b0 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
335c0 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
335d0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
335e0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
335f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
33600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
33610 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
33620 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
33630 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {H16604} SQLite 
33640 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
33650 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
33660 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33670 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33680 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
33690 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
336a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
336b0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
336c0 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
336d0 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
336e0 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
336f0 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
33700 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
33710 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
33720 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
33730 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 73   {H16606} Succes
33740 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
33750 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33760 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
33770 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
33780 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
33790 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
337a0 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
337b0 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
337c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
337d0 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
337e0 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74  ** {H16609} If t
337f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
33800 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
33810 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33820 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
33830 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
33840 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
33850 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
33860 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
33870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
33880 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33890 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
338a0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  Lite..**.** {H16
338b0 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
338c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
338d0 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
338e0 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
338f0 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {H16615} A col
33900 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33910 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
33920 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33930 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
33940 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
33950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
33960 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  se()]..**.** {H1
33970 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
33980 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
33990 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
339a0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
339b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
339c0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
339d0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
339e0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
339f0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
33a00 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
33a10 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
33a20 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
33a30 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  f F..**.** {H166
33a40 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
33a50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33a60 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
33a70 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
33a80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
33a90 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
33aa0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
33ac0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
33ad0 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
33ae0 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
33af0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
33b00 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {H16624} Foll
33b10 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
33b20 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33b30 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
33b40 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
33b50 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
33b60 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
33b70 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
33b80 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
33b90 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
33ba0 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  ions on the [dat
33bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33bc0 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
33bd0 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
33be0 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
33bf0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
33c00 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48  amed X..**.** {H
33c10 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
33c20 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33c30 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
33c40 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
33c50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
33c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33c70 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
33c80 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
33c90 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
33ca0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
33cb0 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
33cc0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
33cd0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
33ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
33cf0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
33d00 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68  *.** {H16630} Wh
33d10 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
33d20 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
33d30 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
33d40 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
33d50 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
33d60 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
33d70 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
33d80 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
33d90 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
33da0 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
33db0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
33dc0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
33dd0 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
33de0 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
33df0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
33e00 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
33e10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33e20 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
33e30 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
33e40 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
33e50 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
33e60 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
33e70 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
33e80 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
33e90 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33eb0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33ec0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33ed0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33ee0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
33ef0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
33f00 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
33f10 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33f20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
33f30 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
33f40 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
33f50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
33f60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
33f70 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
33f80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
33f90 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
33fa0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
33fb0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
33fc0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33fd0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33fe0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
33ff0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
34000 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
34010 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
34020 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
34030 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
34040 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
34050 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34060 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
34070 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
34080 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
34090 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
340a0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
340b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
340c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
340d0 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
340e0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
340f0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
34100 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
34110 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
34120 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
34130 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
34140 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
34150 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34160 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
34170 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
34180 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
34190 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
341a0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
341b0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
341c0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
341d0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
341e0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
341f0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
34200 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
34210 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
34220 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
34230 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
34240 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
34250 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
34260 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
34270 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
34280 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
34290 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
342a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
342b0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
342c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
342d0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
342e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
342f0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
34300 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34310 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
34320 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
34330 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
34340 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
34350 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
34360 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
34370 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
34380 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
34390 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
343a0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
343b0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
343c0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
343d0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
343e0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
343f0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
34400 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
34410 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
34420 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
34430 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
34440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
34450 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
34460 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
34470 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
34480 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
34490 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
344a0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
344b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
344c0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
344d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
344e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
344f0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34500 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32  S:.**.** {H16702
34510 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
34520 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34530 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34540 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
34550 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
34560 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34570 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
34580 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
34590 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
345a0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
345b0 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
345c0 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
345d0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
345e0 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
345f0 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
34600 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
34610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
34620 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
34630 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
34640 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
34650 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68  ** {H16704} Each
34660 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
34670 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
34680 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
34690 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
346a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
346b0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
346c0 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
346d0 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
346e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
346f0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
34700 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
34710 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
34720 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
34730 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
34740 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68  *.** {H16706} Th
34750 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
34760 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
34770 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
34780 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
34790 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
347a0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
347b0 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
347c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
347d0 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
347e0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
347f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34800 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
34810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
34820 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
34830 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
34840 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
34850 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
34860 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
34870 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34880 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
34890 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
348a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
348b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
348c0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
348d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
348e0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
348f0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
34900 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34910 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
34920 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
34930 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
34940 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
34950 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
34960 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
34970 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
34980 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
34990 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
349a0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
349b0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
349c0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
349d0 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
349e0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
349f0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
34a00 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
34a10 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
34a20 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
34a30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34a40 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34a50 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34a60 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34a70 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
34a80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
34a90 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
34aa0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
34ab0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
34ac0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
34ad0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
34ae0 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
34af0 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
34b00 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
34b10 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
34b20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
34b30 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
34b40 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
34b50 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
34b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
34b70 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
34b80 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
34b90 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
34ba0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
34bb0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
34bc0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
34bd0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
34be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34bf0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
34c00 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
34c10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
34c20 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
34c30 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
34c40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
34c50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
34c60 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
34c70 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
34c80 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
34c90 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
34ca0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
34cb0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
34cc0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
34cd0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
34ce0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
34cf0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
34d00 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
34d10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34d20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
34d30 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
34d40 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
34d50 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
34d60 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
34d70 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
34d80 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
34d90 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
34da0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
34db0 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
34dc0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
34dd0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
34de0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
34df0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
34e00 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
34e10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
34e20 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
34e30 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
34e40 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
34e50 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
34e60 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
34e70 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
34e80 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  bject..**.** INV
34e90 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
34ea0 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73 71 6c  H10533} The [sql
34eb0 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
34ec0 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b 65 73  nterface invokes
34ed0 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20   the xSleep.**  
34ee0 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f          method o
34ef0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
34f00 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53 5d 20  qlite3_vfs|VFS] 
34f10 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20  in order to.**  
34f20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e 64 20          suspend 
34f30 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
34f40 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
34f50 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  for at least.** 
34f60 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69           M milli
34f70 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  seconds..**.** {
34f80 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73 71 6c  H10536} The [sql
34f90 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69  ite3_sleep(M)] i
34fa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34fb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
34fc0 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c 6c 69  *          milli
34fd0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
34fe0 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75 65 73   actually reques
34ff0 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65 72 61  ted of the opera
35000 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
35010 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68 20 6d   system, which m
35020 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
35030 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65  han the paramete
35040 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  r M..*/.int sqli
35050 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
35060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35070 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
35080 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
35090 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48 31 30  orary Files {H10
350a0 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  310}.**.** If th
350b0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
350c0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
350d0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
350e0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
350f0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
35100 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
35110 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
35120 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
35130 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
35140 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
35150 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
35160 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
35170 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
35180 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
35190 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
351a0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
351b0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
351c0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
351d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
351e0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
351f0 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
35200 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
35210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35220 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
35230 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
35240 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
35250 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35260 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35270 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35280 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
35290 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
352a0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
352b0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
352c0 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
352d0 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
352e0 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
352f0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
35300 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
35310 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
35320 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
35330 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
35340 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30  de {H12930} <S60
35350 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
35360 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
35370 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
35380 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35390 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
353a0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
353b0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
353c0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
353d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
353e0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
353f0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
35400 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
35410 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
35420 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
35430 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
35440 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
35450 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
35460 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
35470 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35480 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35490 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
354a0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
354b0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
354c0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
354d0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
354e0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
354f0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
35500 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
35510 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
35520 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
35530 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
35540 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
35550 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35560 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35570 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35580 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35590 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
355a0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
355b0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
355c0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
355d0 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
355e0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
355f0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
35600 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
35610 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
35620 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
35630 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35640 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54  **.** {H12931} T
35650 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
35660 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
35670 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35680 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
35690 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
356a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
356b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
356c0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
356d0 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
356e0 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
356f0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
35700 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
35710 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
35720 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
35730 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  H12933} Autocomm
35740 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
35750 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
35760 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
35770 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
35780 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
35790 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
357a0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
357b0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
357c0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
357d0 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
357e0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
357f0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d  :.**.** {A12936}
35800 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
35810 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
35820 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
35830 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
35850 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
35860 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
35870 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
35880 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35890 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
358a0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
358b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
358c0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
358d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
358e0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
358f0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
35900 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
35910 74 20 7b 48 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a  t {H13120}.**.**
35920 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
35930 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65  handle interface
35940 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61   returns the [da
35950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35960 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20  n] handle.** to 
35970 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65  which a [prepare
35980 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c  d statement] bel
35990 6f 6e 67 73 2e 20 20 54 68 65 20 64 61 74 61 62  ongs.  The datab
359a0 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72  ase handle retur
359b0 6e 65 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ned by.** sqlite
359c0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
359d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
359e0 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73   handle that was
359f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
35a00 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
35a10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
35a20 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
35a30 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
35a40 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
35a50 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
35a60 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
35a70 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  t place..**.** I
35a80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
35a90 20 7b 48 31 33 31 32 33 7d 20 54 68 65 20 5b 73   {H13123} The [s
35aa0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35ab0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
35ac0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
35ae0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35af0 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
35b00 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ated with the.**
35b10 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
35b20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
35b30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
35b40 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
35b50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
35b60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35b70 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
35b80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35b90 74 20 7b 48 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {H13140}.**.**
35ba0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
35bb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35bc0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
35bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35be0 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
35bf0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
35c00 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
35c10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
35c20 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
35c30 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
35c40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35c50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35c60 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
35c70 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
35c80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35c90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35ca0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
35cb0 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
35cc0 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
35cd0 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
35ce0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
35cf0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
35d00 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
35d10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
35d20 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b  143} If D is a [
35d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35d40 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  ion] that holds 
35d50 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
35d60 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69          unfinali
35d70 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  zed [prepared st
35d80 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
35d90 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
35da0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
35db0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  hen [sqlite3_nex
35dc0 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
35dd0 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
35de0 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
35df0 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20           to one 
35e00 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
35e10 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
35e20 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a  iated with D..**
35e30 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20  .** {H13146} If 
35e40 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
35e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
35e60 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e  t holds no unfin
35e70 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20  alized.**       
35e80 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
35e90 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
35ea0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35eb0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
35ec0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
35ed0 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
35ee0 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
35ef0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
35f00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d  ..**.** {H13149}
35f10 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 65 70   If S is a [prep
35f20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35f30 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
35f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
35f50 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53  *          and S
35f60 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74   is not the last
35f70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
35f80 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a  ent in D, then.*
35f90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35fa0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
35fb0 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
35fc0 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
35fd0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
35fe0 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  to the next prep
35ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
36000 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a  n D after S..**.
36010 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53  ** {H13152} If S
36020 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72   is the last [pr
36030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36040 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  ] in the.**     
36050 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
36060 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65  onnection] D the
36070 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  n the [sqlite3_n
36080 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a  ext_stmt(D, S)].
36090 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
360a0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
360b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
360c0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74  .*/.sqlite3_stmt
360d0 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   *sqlite3_next_s
360e0 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62  tmt(sqlite3 *pDb
360f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  , sqlite3_stmt *
36100 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
36110 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20  API3REF: Commit 
36120 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74  And Rollback Not
36130 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
36140 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36  cks {H12950} <S6
36150 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0400>.**.** The 
36160 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
36170 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
36180 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
36190 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
361a0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
361b0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
361c0 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
361d0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
361e0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
361f0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
36200 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36210 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
36220 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
36230 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
36240 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71  idden..** The sq
36250 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
36260 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
36270 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
36280 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
36290 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
362a0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
362b0 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
362c0 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
362d0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
362e0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
362f0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36300 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
36310 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
36320 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
36330 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41  idden..** The pA
36340 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
36350 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
36360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
36370 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
36380 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
36390 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
363a0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
363b0 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
363c0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
363d0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
363e0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
363f0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
36400 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
36410 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20  ed, its.** pArg 
36420 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
36430 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
36440 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
36450 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
36460 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
36470 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
36480 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46  allback..**.** F
36490 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
364a0 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74  of this API, a t
364b0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61  ransaction is sa
364c0 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a  id to have been.
364d0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69  ** rolled back i
364e0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52  f an explicit "R
364f0 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65  OLLBACK" stateme
36500 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20  nt is executed, 
36510 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f  or.** an error o
36520 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75  r constraint cau
36530 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20  ses an implicit 
36540 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75  rollback to occu
36550 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  r..** The rollba
36560 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
36570 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
36580 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
36590 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
365a0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
365b0 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
365c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
365d0 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f  losed..** The ro
365e0 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
365f0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
36600 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
36610 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
36620 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
36630 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
36640 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
36650 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f  * <todo> Check o
36660 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a  n this </todo>.*
36670 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
36680 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20  .**.** {H12951} 
36690 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
366a0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
366b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
366c0 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
366d0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
366e0 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
366f0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
36700 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
36710 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
36720 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
36730 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s on the [databa
36740 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36750 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d  ..**.** {H12952}
36760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
36770 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
36780 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
36790 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
367a0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  nt.**          f
367b0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
367c0 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73   call with the s
367d0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
367e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
367f0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
36800 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61   on the first ca
36810 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ll for a particu
36820 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  lar database con
36830 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
36840 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68 20 63   {H12953} Each c
36850 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36860 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f  commit_hook()] o
36870 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61  verwrites the ca
36880 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
36890 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79     registered by
368a0 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a   prior calls..**
368b0 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20  .** {H12954} If 
368c0 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74  the F argument t
368d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  o [sqlite3_commi
368e0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
368f0 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
36900 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d     then the comm
36910 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
36920 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64   is canceled and
36930 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20   no callback.** 
36940 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
36950 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73  ked when a trans
36960 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a  action commits..
36970 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49  **.** {H12955} I
36980 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c  f the commit cal
36990 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
369a0 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  n-zero then the 
369b0 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20  commit is.**    
369c0 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20        converted 
369d0 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e  into a rollback.
369e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20  .**.** {H12961} 
369f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  The [sqlite3_rol
36a00 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50  lback_hook(D,F,P
36a10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
36a20 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20  isters the.**   
36a30 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
36a40 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
36a50 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
36a60 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
36a70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
36a80 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
36a90 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64  s back on the [d
36aa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36ab0 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  on] D..**.** {H1
36ac0 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2962} The [sqlit
36ad0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36ae0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
36af0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
36b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
36b10 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
36b20 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
36b30 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  h the same.**   
36b40 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
36b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
36b60 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66  or NULL on the f
36b70 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  irst call.**    
36b80 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74        for a part
36b90 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  icular database 
36ba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
36bb0 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63  .** {H12963} Eac
36bc0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
36bd0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
36be0 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74  ()] overwrites t
36bf0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  he callback.**  
36c00 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
36c10 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  ed by prior call
36c20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34  s..**.** {H12964
36c30 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d  } If the F argum
36c40 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
36c50 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
36c60 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a  F,P)] is NULL.**
36c70 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
36c80 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
36c90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e   callback is can
36ca0 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c  celed and no cal
36cb0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
36cc0 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65    is invoked whe
36cd0 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  n a transaction 
36ce0 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76  rolls back..*/.v
36cf0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
36d00 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
36d10 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
36d20 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
36d30 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36d40 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
36d50 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
36d60 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
36d70 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
36d80 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
36d90 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  on Callbacks {H1
36da0 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2970} <S60400>.*
36db0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36dc0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
36dd0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
36de0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
36df0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
36e00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36e10 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
36e20 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
36e30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
36e40 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36e50 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
36e60 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
36e70 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e  r deleted..** An
36e80 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
36e90 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
36ea0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
36eb0 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
36ec0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
36ed0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
36ee0 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
36ef0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
36f00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
36f10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
36f20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
36f30 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
36f40 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
36f50 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eted..** The fir
36f60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
36f70 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
36f80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
36f90 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
36fa0 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
36fb0 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20  _hook()..** The 
36fc0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
36fd0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
36fe0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
36ff0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
37000 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
37010 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
37020 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
37030 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
37040 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
37050 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
37060 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  ..** The third a
37070 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
37080 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
37090 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
370a0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
370b0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
370c0 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
370d0 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
370e0 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c  ow..** The final
370f0 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
37100 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64  ter is the rowid
37110 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20   of the row. In 
37120 74 68 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61  the case of.** a
37130 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
37140 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74 65  s the rowid afte
37150 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
37160 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
37170 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
37180 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
37190 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
371a0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
371b0 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
371c0 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
371d0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
371e0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ce)..**.** If an
371f0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
37200 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
37210 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41  gistered, its pA
37220 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72  rg value.** is r
37230 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
37240 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
37250 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  rned..**.** INVA
37260 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
37270 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  12971} The [sqli
37280 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37290 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
372a0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
372b0 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
372c0 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20    function F to 
372d0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
372e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
372f0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
37300 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72         a table r
37310 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20  ow is modified, 
37320 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c  inserted, or del
37330 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20  eted on.**      
37340 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73      the [databas
37350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
37360 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20  .**.** {H12973} 
37370 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  The [sqlite3_upd
37380 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
37390 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
373a0 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  ns the value.** 
373b0 20 20 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f           of P fo
373c0 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  r the previous c
373d0 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  all on the same 
373e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
373f0 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20  tion] D,.**     
37400 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72       or NULL for
37410 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e   the first call.
37420 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20  .**.** {H12975} 
37430 49 66 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  If the update ho
37440 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e  ok callback F in
37450 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
37460 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a  _hook(D,F,P)].**
37470 20 20 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c            is NUL
37480 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70  L then the no up
37490 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61  date callbacks a
374a0 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b  re made..**.** {
374b0 48 31 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c  H12977} Each cal
374c0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70  l to [sqlite3_up
374d0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
374e0 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f  ] overrides prio
374f0 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20  r calls.**      
37500 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20      to the same 
37510 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65  interface on the
37520 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37530 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
37540 2a 0a 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68  *.** {H12979} Th
37550 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
37560 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
37570 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72  voked when inter
37580 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20  nal system.**   
37590 20 20 20 20 20 20 20 74 61 62 6c 65 73 20 73 75         tables su
375a0 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73  ch as sqlite_mas
375b0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
375c0 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69  equence are modi
375d0 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  fied..**.** {H12
375e0 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  981} The second 
375f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37600 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b   update callback
37610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37620 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
37630 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
37640 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49  DELETE] or [SQLI
37650 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20  TE_UPDATE],.**  
37660 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e          dependin
37670 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
37680 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
37690 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62  he callback to b
376a0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  e invoked..**.**
376b0 20 7b 48 31 32 39 38 33 7d 20 54 68 65 20 74 68   {H12983} The th
376c0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
376d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
376e0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
376f0 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20   pointers.**    
37700 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65        to zero-te
37710 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
37720 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72 65  trings which are
37730 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
37740 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  e.**          da
37750 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65  tabase and table
37760 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 75   that is being u
37770 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32  pdated...** {H12
37780 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63  985} The final c
37790 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
377a0 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
377b0 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a  f the row after.
377c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
377d0 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a  change occurs..*
377e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
377f0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
37800 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
37810 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
37820 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
37830 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
37840 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
37850 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
37860 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
37870 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
37880 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33  ager Cache {H103
37890 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20  30} <S30900>.** 
378a0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
378b0 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64  d cache} {shared
378c0 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a   cache mode}.**.
378d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
378e0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
378f0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
37900 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
37910 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
37920 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
37930 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
37940 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37950 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
37960 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
37970 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
37980 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
37990 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
379a0 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
379b0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
379c0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a  ent is false..**
379d0 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e  .** Cache sharin
379e0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
379f0 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
37a00 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
37a10 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69   {END}.** This i
37a20 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
37a30 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37a40 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
37a50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
37a60 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
37a70 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
37a80 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
37a90 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
37aa0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63  y..**.** The cac
37ab0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
37ac0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
37ad0 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
37ae0 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
37af0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
37b00 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
37b10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
37b20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
37b30 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
37b40 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
37b50 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
37b60 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
37b70 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
37b80 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
37b90 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
37ba0 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  re opened..**.**
37bb0 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   Virtual tables 
37bc0 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77  cannot be used w
37bd0 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63  ith a shared cac
37be0 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64  he.  When shared
37bf0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
37c00 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
37c10 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
37c20 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20  ()] API used to 
37c30 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74  register.** virt
37c40 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20  ual tables will 
37c50 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e  always return an
37c60 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68   error..**.** Th
37c70 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
37c80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
37c90 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
37ca0 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
37cb0 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73  sabled.** succes
37cc0 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
37cd0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
37ce0 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  rned otherwise..
37cf0 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63  **.** Shared cac
37d00 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
37d10 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
37d20 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
37d30 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
37d40 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
37d50 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
37d60 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
37d70 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
37d80 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
37d90 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
37da0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
37db0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33  TS:.**.** {H1033
37dc0 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
37dd0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
37de0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
37df0 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a  ared_cache(B)].*
37e00 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
37e10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
37e20 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d  e shared cache m
37e30 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73  ode for any subs
37e40 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  equently.**     
37e50 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61       created [da
37e60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37e70 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70  n] in the same p
37e80 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rocess..**.** {H
37e90 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72  10336} When shar
37ea0 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ed cache is enab
37eb0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
37ec0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
37ed0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
37ee0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c  nterface will al
37ef0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
37f00 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  rror..**.** {H10
37f10 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  337} The [sqlite
37f20 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
37f30 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66  cache(B)] interf
37f40 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
37f50 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
37f60 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
37f70 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
37f80 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
37f90 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  essfully..**.** 
37fa0 7b 48 31 30 33 33 39 7d 20 53 68 61 72 65 64 20  {H10339} Shared 
37fb0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
37fc0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f  d by default..*/
37fd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
37fe0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
37ff0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38000 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
38010 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
38020 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33  ory {H17340} <S3
38030 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0220>.**.** The 
38040 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
38050 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
38060 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
38070 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
38080 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
38090 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
380a0 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
380b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
380c0 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
380d0 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
380e0 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73  {END}  Memory us
380f0 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
38100 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
38110 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
38120 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
38130 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
38140 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73  ial memory..** s
38150 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
38160 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
38170 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
38180 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
38190 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
381a0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
381b0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
381c0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a  nt requested..**
381d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
381e0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54  **.** {H17341} T
381f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  he [sqlite3_rele
38200 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69  ase_memory(N)] i
38210 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
38220 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
38230 20 66 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66   free N bytes of
38240 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
38250 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
38260 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20  -essential.**   
38270 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c         memory al
38280 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
38290 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
382a0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ibrary..**.** {H
382b0 31 36 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16342} The [sqli
382c0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
382d0 72 79 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74  ry(N)] returns t
382e0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20  he number.**    
382f0 20 20 20 20 20 20 6f 66 20 62 79 74 65 73 20 61        of bytes a
38300 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77  ctually freed, w
38310 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
38320 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20  re or less.**   
38330 20 20 20 20 20 20 20 74 68 61 6e 20 74 68 65 20         than the 
38340 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
38350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
38360 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
38370 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
38380 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
38390 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
383a0 7a 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30  ze {H17350} <S30
383b0 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  220>.**.** The s
383c0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
383d0 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
383e0 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
383f0 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
38400 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
38410 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
38420 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
38430 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20  y SQLite..** If 
38440 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
38450 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
38460 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
38470 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
38480 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
38490 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
384a0 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
384b0 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
384c0 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
384d0 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
384e0 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
384f0 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
38500 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d  d..**.** The lim
38510 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
38520 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20  ft", because if 
38530 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
38540 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
38550 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
38560 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
38570 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
38580 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
38590 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
385a0 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
385b0 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
385c0 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
385d0 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
385e0 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  * A negative or 
385f0 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
38600 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
38610 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
38620 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
38630 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
38640 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
38650 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
38660 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
38670 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64  austed..** The d
38680 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
38690 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
386a0 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
386b0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
386c0 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
386d0 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
386e0 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
386f0 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
38700 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
38710 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
38720 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
38730 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
38740 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
38750 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73  cation.  This is
38760 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
38770 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73  s.** called a "s
38780 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
38790 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
387a0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
387b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
387c0 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
387d0 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
387e0 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
387f0 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
38800 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
38810 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
38820 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
38830 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
38840 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
38850 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
38860 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
38870 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
38880 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
38890 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
388a0 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
388b0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
388c0 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
388d0 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
388e0 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
388f0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
38900 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
38910 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
38920 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
38930 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
38940 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap