/ Hex Artifact Content
Login

Artifact 3ad63197bdc9fa1623c1e139ee6f39e7d2ccfa5b:


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 35 36 20 32 30 30 38 2f 30  n,v 1.356 2008/0
05f0: 36 2f 32 35 20 31 30 3a 33 34 3a 33 35 20 64 61  6/25 10:34:35 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a  nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  ndif../*.** Ensu
0750: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
0760: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
0770: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
0780: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
0790: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
07a0: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
07b0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
07c0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
07d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
07e0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
07f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0800: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
0810: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
0820: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
0830: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b  ersion Numbers {
0840: 46 31 30 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10010}.**.** 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 46 31 30 30 31 31 7d 20 54 68  *.** {F10011} 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 0a 2a 2a 20 20 20 20 20 20 20 20   file.**        
0bf0: 20 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61    evaluates to a
0c00: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0c10: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0c20: 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20  te version.**   
0c30: 20 20 20 20 20 20 20 77 69 74 68 20 77 68 69 63         with whic
0c40: 68 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  h the header fil
0c50: 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e  e is associated.
0c60: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20  .**.** {F10014} 
0c70: 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  The SQLITE_VERSI
0c80: 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e  ON_NUMBER #defin
0c90: 65 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  e resolves to an
0ca0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
0cb0: 20 20 20 20 20 77 69 74 68 20 74 68 65 20 76 61       with the va
0cc0: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0cd0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0ce0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a  re X, Y, and Z.*
0cf0: 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 74  *          are t
0d00: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0d10: 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c  , minor version,
0d20: 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d   and release num
0d30: 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ber..*/.#define 
0d40: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
0d50: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
0d60: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
0d70: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0d80: 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45   --VERSION-NUMBE
0d90: 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  R--../*.** CAPI3
0da0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
0db0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
0dc0: 6d 62 65 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a  mbers {F10020}.*
0dd0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
0de0: 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a  te3_version.**.*
0df0: 2a 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73  * These features
0e00: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
0e10: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
0e20: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
0e30: 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51  SION].** and [SQ
0e40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e50: 42 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e  BER] #defines in
0e60: 20 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74   the header, but
0e70: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a   are associated.
0e80: 2a 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ** with the libr
0e90: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
0ea0: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
0eb0: 20 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61   Cautious progra
0ec0: 6d 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69  mmers might.** i
0ed0: 6e 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69  nclude a check i
0ee0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
0ef0: 69 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68  ion to verify th
0f00: 61 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  at.** sqlite3_li
0f10: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
0f20: 29 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  ) always returns
0f30: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53   the value.** [S
0f40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f50: 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MBER]..**.** The
0f60: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
0f70: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
0f80: 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20  eturns the same 
0f90: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
0fa0: 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69  s.** in the sqli
0fb0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
0fc0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
0fd0: 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  The function is 
0fe0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
0ff0: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
1000: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
1010: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20  lly do not have 
1020: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1030: 20 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74   string.** const
1040: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
1050: 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  DLL..**.** INVAR
1060: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1070: 30 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0021} The [sqlit
1080: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1090: 6d 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  mber()] interfac
10a0: 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
10b0: 20 20 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72        an integer
10c0: 20 65 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54   equal to [SQLIT
10d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
10e0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 32  ]..**.** {F10022
10f0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
1100: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63  ersion] string c
1110: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1120: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1130: 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51   text of the [SQ
1140: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74  LITE_VERSION] st
1150: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ring..**.** {F10
1160: 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  023} The [sqlite
1170: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20  3_libversion()] 
1180: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1190: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
11a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
11b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20  qlite3_version] 
11c0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e  string constant.
11d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
11e0: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
11f0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
1200: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1210: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1220: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
1230: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1240: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
1250: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
1260: 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c   To See If The L
1270: 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64  ibrary Is Thread
1280: 73 61 66 65 20 7b 46 31 30 31 30 30 7d 0a 2a 2a  safe {F10100}.**
1290: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62  .** SQLite can b
12a0: 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  e compiled with 
12b0: 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78  or without mutex
12c0: 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65  es.  When.** the
12d0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12e0: 46 45 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  FE C preprocesso
12f0: 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c  r macro is true,
1300: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1310: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1320: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1330: 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63  .  When that mac
1340: 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20  ro is false,.** 
1350: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20  the mutexes are 
1360: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75  omitted.  Withou
1370: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69  t the mutexes, i
1380: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a  t is not safe.**
1390: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63   to use SQLite c
13a0: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d  oncurrently from
13b0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
13c0: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61  hread..**.** Ena
13d0: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e  bling mutexes in
13e0: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c  curs a measurabl
13f0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65  e performance pe
1400: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20  nalty..** So if 
1410: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f  speed is of utmo
1420: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69  st importance, i
1430: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f  t makes sense to
1440: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
1450: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f  mutexes.  But fo
1460: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79  r maximum safety
1470: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  , mutexes should
1480: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   be enabled..** 
1490: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
14a0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
14b0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
14c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
14d0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
14e0: 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d  sed by a program
14f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1500: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1510: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1520: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1530: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1540: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1550: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1560: 6f 66 20 74 68 65 20 53 51 4c 49 54 45 5f 54 48  of the SQLITE_TH
1570: 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a  READSAFE macro..
1580: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1590: 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d  :.**.** {F10101}
15a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 68   The [sqlite3_th
15b0: 72 65 61 64 73 61 66 65 28 29 5d 20 66 75 6e 63  readsafe()] func
15c0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
15d0: 7a 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20  zero if.**      
15e0: 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20 63      SQLite was c
15f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 69 74 73  ompiled with its
1600: 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64   mutexes enabled
1610: 20 6f 72 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20   or zero.**     
1620: 20 20 20 20 20 69 66 20 53 51 4c 69 74 65 20 77       if SQLite w
1630: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1640: 20 6d 75 74 65 78 65 73 20 64 69 73 61 62 6c 65   mutexes disable
1650: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
1660: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
1670: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
1680: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
1690: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20  nnection Handle 
16a0: 7b 46 31 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F12000}.** KEYW
16b0: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
16c0: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
16d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16e0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
16f0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
1700: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
1710: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
1720: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
1730: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
1740: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
1750: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
1760: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
1770: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
1780: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
1790: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
17a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
17b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
17c0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
17d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
17e0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
17f0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
1800: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
1810: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
1820: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
1830: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
1840: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
1850: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
1860: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
1870: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
1880: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
1890: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
18a0: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
18b0: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
18c0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
18d0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
18e0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
18f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
1900: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
1910: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
1920: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
1930: 65 73 20 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b  es {F10200}.** K
1940: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
1950: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
1960: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
1970: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
1980: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
1990: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
19a0: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
19b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
19c0: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
19d0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
19e0: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
19f0: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
1a00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
1a10: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
1a20: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
1a30: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
1a40: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
1a50: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
1a60: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
1a70: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
1a80: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
1a90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
1aa0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ly..**.** INVARI
1ab0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
1ac0: 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  201} The [sqlite
1ad0: 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  _int64] and [sql
1ae0: 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70 65  ite3_int64] type
1af0: 73 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20 20  s specify.**    
1b00: 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20 73        a 64-bit s
1b10: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1b20: 2a 0a 2a 2a 20 7b 46 31 30 32 30 32 7d 20 54 68  *.** {F10202} Th
1b30: 65 20 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  e [sqlite_uint64
1b40: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75  ] and [sqlite3_u
1b50: 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73 70 65  int64] types spe
1b60: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  cify.**         
1b70: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1b80: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23  ed integer..*/.#
1b90: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
1ba0: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
1bb0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
1bc0: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
1bd0: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
1be0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
1bf0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
1c00: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
1c10: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
1c20: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
1c30: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
1c40: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
1c50: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
1c60: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
1c70: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
1c80: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
1c90: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
1ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1cb0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1cc0: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
1cd0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
1ce0: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
1cf0: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
1d00: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
1d10: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
1d20: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
1d30: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
1d40: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
1d50: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
1d60: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
1d70: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
1d80: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
1d90: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
1da0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
1db0: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
1dc0: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
1dd0: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
1de0: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
1df0: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
1e00: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
1e10: 6e 65 63 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d  nection {F12010}
1e20: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
1e30: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
1e40: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
1e50: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
1e60: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1e70: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
1e80: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
1e90: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
1ea0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1eb0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
1ec0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
1ed0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
1ee0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
1ef0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
1f00: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1f10: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
1f20: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
1f30: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
1f40: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
1f50: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
1f60: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1f70: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
1f80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f90: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
1fa0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1fb0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
1fc0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
1fd0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
1fe0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
1ff0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2000: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2010: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2020: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2030: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2040: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2050: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2060: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2070: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2080: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2090: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
20a0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
20b0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
20c0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
20d0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
20e0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
20f0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2100: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
2110: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2120: 31 32 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  12011} The [sqli
2130: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74  te3_close()] int
2140: 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
2150: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2160: 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ect.**          
2170: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 70  allocated by a p
2180: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71  rior call to [sq
2190: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
21a0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21b0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
21c0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
21d0: 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  v2()]..**.** {F1
21e0: 32 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2012} The [sqlit
21f0: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63  e3_close()] func
2200: 74 69 6f 6e 20 72 65 6c 65 61 73 65 73 20 61 6c  tion releases al
2210: 6c 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 62 79  l memory used by
2220: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2230: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2240: 63 6c 6f 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20  closes all open 
2250: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  files..**.** {F1
2260: 32 30 31 33 7d 20 49 66 20 74 68 65 20 64 61 74  2013} If the dat
2270: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2280: 20 63 6f 6e 74 61 69 6e 73 20 5b 70 72 65 70 61   contains [prepa
2290: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
22a0: 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
22b0: 20 68 61 76 65 20 6e 6f 74 20 62 65 65 6e 20 5b   have not been [
22c0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22d0: 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 2c 0a 2a   | finalized],.*
22e0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
22f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2300: 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2310: 45 5f 42 55 53 59 5d 20 61 6e 64 20 6c 65 61 76  E_BUSY] and leav
2320: 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
2330: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  he connection op
2340: 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  en..**.** {F1201
2350: 34 7d 20 50 61 73 73 69 6e 67 20 73 71 6c 69 74  4} Passing sqlit
2360: 65 33 5f 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c  e3_close() a NUL
2370: 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2380: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2390: 2a 0a 2a 2a 20 7b 46 31 32 30 31 39 7d 20 57 68  *.** {F12019} Wh
23a0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  en [sqlite3_clos
23b0: 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  e()] is invoked 
23c0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
23d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20  onnection].**   
23e0: 20 20 20 20 20 20 20 74 68 61 74 20 68 61 73 20         that has 
23f0: 61 20 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61  a pending transa
2400: 63 74 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73  ction, the trans
2410: 61 63 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a  action shall be.
2420: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c  **          roll
2430: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 4c  ed back..**.** L
2440: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
2450: 2a 20 7b 55 31 32 30 31 35 7d 20 54 68 65 20 70  * {U12015} The p
2460: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2470: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75  ite3_close()] mu
2480: 73 74 20 62 65 20 61 6e 20 5b 73 71 6c 69 74 65  st be an [sqlite
2490: 33 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20  3] object.**    
24a0: 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 70 72        pointer pr
24b0: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
24c0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
24d0: 6f 70 65 6e 28 29 5d 20 6f 72 20 74 68 65 0a 2a  open()] or the.*
24e0: 2a 20 20 20 20 20 20 20 20 20 20 65 71 75 69 76  *          equiv
24f0: 61 6c 65 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  alent, or NULL..
2500: 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54  **.** {U12016} T
2510: 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  he parameter to 
2520: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2530: 5d 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  ] must not have 
2540: 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a  been previously.
2550: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6c 6f 73  **          clos
2560: 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2570: 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  e3_close(sqlite3
2580: 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20   *);../*.** The 
2590: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
25a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
25b0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
25c0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
25d0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
25e0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
25f0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2600: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
2610: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
2620: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
2630: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
2640: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
2650: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
2660: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
2670: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
2680: 6e 74 65 72 66 61 63 65 20 7b 46 31 32 31 30 30  nterface {F12100
2690: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
26a0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
26b0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
26c0: 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75 6e 6e  ient way of runn
26d0: 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  ing one or more.
26e0: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
26f0: 73 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  s without having
2700: 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f 74 20   to write a lot 
2710: 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68 65 20  of C code.  The 
2720: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a  UTF-8 encoded.**
2730: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
2740: 61 72 65 20 70 61 73 73 65 64 20 69 6e 20 61 73  are passed in as
2750: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2760: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2770: 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20  _exec()..** The 
2780: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2790: 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62 79 20  valuated one by 
27a0: 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72  one until either
27b0: 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20   an error or.** 
27c0: 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69 73 20  an interrupt is 
27d0: 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20  encountered, or 
27e0: 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65 20 61  until they are a
27f0: 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20 33 72  ll done.  The 3r
2800: 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  d parameter.** i
2810: 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61  s an optional ca
2820: 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73 20 69  llback that is i
2830: 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
2840: 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e 79 20  each row of any 
2850: 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73  query.** results
2860: 20 70 72 6f 64 75 63 65 64 20 62 79 20 74 68 65   produced by the
2870: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
2880: 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
2890: 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72 65 0a  ter tells where.
28a0: 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e 79 20  ** to write any 
28b0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a  error messages..
28c0: 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f 72 20  **.** The error 
28d0: 6d 65 73 73 61 67 65 20 70 61 73 73 65 64 20 62  message passed b
28e0: 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20  ack through the 
28f0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  5th parameter is
2900: 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f   held.** in memo
2910: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2920: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2930: 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64 20 61  ()].  To avoid a
2940: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a   memory leak,.**
2950: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61 70 70   the calling app
2960: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
2970: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
2980: 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72  ee()] on any err
2990: 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 72 65  or.** message re
29a0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74  turned through t
29b0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
29c0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
29d0: 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74  ished using.** t
29e0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
29f0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
2a00: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2a10: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a20: 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  r is NULL or an 
2a30: 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20  empty string.** 
2a40: 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  or a string cont
2a50: 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74  aining only whit
2a60: 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65  espace and comme
2a70: 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c  nts, then no SQL
2a80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 61  .** statements a
2a90: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
2aa0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
2ab0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a   not changed..**
2ac0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2ad0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ae0: 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
2af0: 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b  in terms of.** [
2b00: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b10: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2b20: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
2b30: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b40: 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  ]..** The sqlite
2b50: 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69 6e 65  3_exec() routine
2b60: 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f   does nothing to
2b70: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
2b80: 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e  at cannot be don
2b90: 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  e.** by [sqlite3
2ba0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2bb0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2bc0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2bd0: 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  inalize()]..**.*
2be0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2bf0: 0a 2a 2a 20 7b 46 31 32 31 30 31 7d 20 41 20 73  .** {F12101} A s
2c00: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
2c10: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2c20: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
2c30: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2c40: 61 6c 6c 20 65 76 61 6c 75 61 74 65 20 61 6c 6c  all evaluate all
2c50: 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e   of the UTF-8 en
2c60: 63 6f 64 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e  coded, semicolon
2c70: 2d 73 65 70 61 72 61 74 65 64 0a 2a 2a 20 20 20  -separated.**   
2c80: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
2c90: 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
2ca0: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
2cb0: 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68 65  ing S within the
2cc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
2cd0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
2ce0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cf0: 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ] D..**.** {F121
2d00: 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72  02} If the S par
2d10: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2d20: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
2d30: 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  E)] is NULL then
2d40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d50: 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20   actions of the 
2d60: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2d70: 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69  be the same as i
2d80: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d90: 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65    S parameter we
2da0: 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  re an empty stri
2db0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30  ng..**.** {F1210
2dc0: 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  4} The return va
2dd0: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
2de0: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
2df0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
2e00: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
2e10: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72  SQL statements r
2e20: 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  un successfully 
2e30: 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  and to completio
2e40: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35  n..**.** {F12105
2e50: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
2e60: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
2e70: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
2e80: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
2e90: 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a  *          non-z
2ea0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
2eb0: 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74   if any SQL stat
2ec0: 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a  ement fails..**.
2ed0: 2a 2a 20 7b 46 31 32 31 30 37 7d 20 49 66 20 6f  ** {F12107} If o
2ee0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2ef0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
2f00: 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69   handed to [sqli
2f10: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
2f20: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72          return r
2f30: 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33  esults and the 3
2f40: 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
2f50: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a  not NULL, then.*
2f60: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
2f70: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2f80: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2f90: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2fa0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
2fb0: 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63       invoked onc
2fc0: 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f  e for each row o
2fd0: 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20  f result..**.** 
2fe0: 7b 46 31 32 31 31 30 7d 20 49 66 20 74 68 65 20  {F12110} If the 
2ff0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3000: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75   a non-zero valu
3010: 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e then [sqlite3_
3020: 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20  exec()].**      
3030: 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20      shall abort 
3040: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
3050: 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c  t it is currentl
3060: 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a  y evaluating,.**
3070: 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61            skip a
3080: 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ll subsequent SQ
3090: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  L statements, an
30a0: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
30b0: 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _ABORT]..**.** {
30c0: 46 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c  F12113} The [sql
30d0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
30e0: 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20  tine shall pass 
30f0: 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65  its 4th paramete
3100: 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20  r through.**    
3110: 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74        as the 1st
3120: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
3130: 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
3140: 2a 20 7b 46 31 32 31 31 36 7d 20 54 68 65 20 5b  * {F12116} The [
3150: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3160: 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74 68 65  routine sets the
3170: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3180: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
3190: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
31a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
31b0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75  olumns in the cu
31c0: 72 72 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20  rrent row of.** 
31d0: 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e           result.
31e0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 39 7d 20  .**.** {F12119} 
31f0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3200: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74  c()] routine set
3210: 73 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  s the 3rd parame
3220: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3230: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
3240: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f  to be an array o
3250: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3260: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
3270: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
3280: 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f  lues for each co
3290: 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
32a0: 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72  ent result set r
32b0: 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  ow as.**        
32c0: 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20    obtained from 
32d0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32e0: 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  text()]..**.** {
32f0: 46 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c  F12122} The [sql
3300: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3310: 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 34 74  tine sets the 4t
3320: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  h parameter of i
3330: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
3340: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e  allback to be an
3350: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3360: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f  rs to strings ho
3370: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  lding the.**    
3380: 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72        names of r
3390: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73  esult columns as
33a0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
33b0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
33c0: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ame()]..**.** {F
33d0: 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72  12125} If the 3r
33e0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
33f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3400: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20  is NULL then.** 
3410: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3420: 33 5f 65 78 65 63 28 29 5d 20 6e 65 76 65 72 20  3_exec()] never 
3430: 69 6e 76 6f 6b 65 73 20 61 20 63 61 6c 6c 62 61  invokes a callba
3440: 63 6b 2e 20 20 41 6c 6c 20 71 75 65 72 79 0a 2a  ck.  All query.*
3450: 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
3460: 74 73 20 61 72 65 20 73 69 6c 65 6e 74 6c 79 20  ts are silently 
3470: 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a  discarded..**.**
3480: 20 7b 46 31 32 31 33 31 7d 20 49 66 20 61 6e 20   {F12131} If an 
3490: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
34a0: 6c 65 20 70 61 72 73 69 6e 67 20 6f 72 20 65 76  le parsing or ev
34b0: 61 6c 75 61 74 69 6e 67 20 61 6e 79 20 6f 66 20  aluating any of 
34c0: 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  the SQL.**      
34d0: 20 20 20 20 68 61 6e 64 65 64 20 69 6e 20 74 68      handed in th
34e0: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f 66  e S parameter of
34f0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3500: 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69  ,S,C,A,E)] and i
3510: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
3520: 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 73  e E parameter is
3530: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
3540: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3550: 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20   shall store.** 
3560: 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20 61           in *E a
3570: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
3580: 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74  ror message writ
3590: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
35a0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20  obtained.**     
35b0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74       from [sqlit
35c0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
35d0: 0a 2a 2a 20 7b 46 31 32 31 33 34 7d 20 54 68 65  .** {F12134} The
35e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
35f0: 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69  ,S,C,A,E)] routi
3600: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  ne shall set the
3610: 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
3620: 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c        *E to NULL
3630: 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c   if E is not NUL
3640: 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 20  L and there are 
3650: 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a  no errors..**.**
3660: 20 7b 46 31 32 31 33 37 7d 20 54 68 65 20 5b 73   {F12137} The [s
3670: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3680: 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e  C,A,E)] function
3690: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 5b   shall set the [
36a0: 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20  error code].**  
36b0: 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73          and mess
36c0: 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76  age accessible v
36d0: 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
36e0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
36f0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
3700: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
3710: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3720: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 38 7d  ..**.** {F12138}
3730: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
3740: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3750: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3760: 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a   is NULL or an.*
3770: 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74 79  *          empty
3780: 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61   string or conta
3790: 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65  ins nothing othe
37a0: 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
37b0: 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20  e, comments,.** 
37c0: 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72 20           and/or 
37d0: 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e  semicolons, then
37e0: 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c   results of [sql
37f0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
3800: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3810: 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c  lite3_errmsg()],
3820: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
3830: 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rmsg16()].**    
3840: 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65        shall rese
3850: 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f  t to indicate no
3860: 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c   errors..**.** L
3870: 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
3880: 2a 20 7b 55 31 32 31 34 31 7d 20 54 68 65 20 66  * {U12141} The f
3890: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
38a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
38b0: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61  )] must be an va
38c0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20  lid and open.** 
38d0: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
38e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
38f0: 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54  **.** {U12142} T
3900: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
3910: 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
3920: 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a  be closed while.
3930: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3940: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3950: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  running..**.** {
3960: 55 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c  U12143} The call
3970: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
3980: 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33  uld use [sqlite3
3990: 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65  _free()] to free
39a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
39b0: 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72   memory that *er
39c0: 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69  rmsg is left poi
39d0: 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68  nting at once th
39e0: 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
39f0: 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e      message is n
3a00: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a10: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20  .**.** {U12145} 
3a20: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
3a30: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3a50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3a60: 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  **          must
3a70: 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
3a80: 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  d while [sqlite3
3a90: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3aa0: 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
3ab0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69  te3_exec(.  sqli
3ac0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
3af0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
3b00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c  const char *sql,
3b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b20: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
3b30: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
3b40: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c  d */.  int (*cal
3b50: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3b60: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c  ,char**,char**),
3b70: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75    /* Callback fu
3b80: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
3b90: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20   *,             
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72         /* 1st ar
3bc0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61  gument to callba
3bd0: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65  ck */.  char **e
3be0: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20  rrmsg           
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
3c10: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
3c20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3c30: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73  EF: Result Codes
3c40: 20 7b 46 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59   {F10210}.** KEY
3c50: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
3c60: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
3c70: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
3c80: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
3c90: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
3ca0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
3cb0: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
3cc0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
3cd0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
3ce0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
3cf0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
3d00: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
3d10: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
3d20: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ure..**.** See a
3d30: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
3d40: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
3d50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
3d60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
3d70: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
3d80: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
3d90: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
3da0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
3db0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
3dc0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
3dd0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
3de0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
3df0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
3e00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3e10: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
3e20: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
3e30: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
3e40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3e50: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
3e60: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
3e70: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
3e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e90: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
3ea0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
3eb0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
3ec0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
3ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
3ee0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
3ef0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
3f00: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
3f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
3f20: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
3f30: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
3f40: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
3f50: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
3f60: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
3f70: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
3f80: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
3f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
3fa0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
3fb0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
3fc0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
3fd0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
3fe0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
3ff0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4000: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4010: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4020: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4030: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
4040: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
4050: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
4060: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
4070: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4080: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
4090: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
40a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
40b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
40c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
40e0: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61   /* NOT USED. Ta
40f0: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
4100: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
4110: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4120: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4130: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4140: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4150: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4160: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4170: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4180: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4190: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
41a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
41b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
41c0: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44    /* NOT USED. D
41d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
41e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
41f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4200: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4210: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4220: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4230: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4240: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4250: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4260: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4270: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4280: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4290: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
42a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
42b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
42c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
42d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
42e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
42f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4300: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4310: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4320: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4330: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4340: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4350: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4360: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4380: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4390: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
43a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
43b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
43c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
43d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
43e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
43f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4400: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4410: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4420: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4430: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4450: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4460: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4470: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4480: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
44a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
44b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
44c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
44d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
44e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
44f0: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4500: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4510: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4520: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4530: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4540: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4550: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4560: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4570: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4580: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4590: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
45a0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
45b0: 6f 64 65 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a  odes {F10220}.**
45c0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
45d0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
45e0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
45f0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4600: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4610: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4620: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4630: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4640: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4650: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4660: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4670: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4680: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4690: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
46a0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
46b0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
46c0: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
46d0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
46e0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
46f0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4700: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4710: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4720: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4730: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4740: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4750: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4760: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4770: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4780: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4790: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
47a0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
47b0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
47c0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
47d0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
47e0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
47f0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4800: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4810: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4820: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4830: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4840: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4850: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4860: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4870: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4880: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4890: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
48a0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
48b0: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
48c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
48d0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
48e0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
48f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4900: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4910: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4920: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4930: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4940: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4950: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4960: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4970: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4980: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4990: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
49a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
49b0: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
49c0: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
49d0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
49e0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
49f0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4a00: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4a10: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20  .**.** {F10223} 
4a20: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4a30: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4a40: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 6c  d result code al
4a50: 77 61 79 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ways contains.**
4a60: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61            a rela
4a70: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75  ted primary resu
4a80: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65  lt code as a pre
4a90: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32  fix..**.** {F102
4aa0: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75  24} Primary resu
4ab0: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f  lt code names co
4ac0: 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22  ntain a single "
4ad0: 5f 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  _" character..**
4ae0: 0a 2a 2a 20 7b 46 31 30 32 32 35 7d 20 45 78 74  .** {F10225} Ext
4af0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4b00: 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20  e names contain 
4b10: 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20  two or more "_" 
4b20: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
4b30: 2a 20 7b 46 31 30 32 32 36 7d 20 54 68 65 20 6e  * {F10226} The n
4b40: 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20  umeric value of 
4b50: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
4b60: 6c 74 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  lt code contains
4b70: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4b80: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4b90: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
4ba0: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
4bb0: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
4bc0: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
4bd0: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
4be0: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
4bf0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4c00: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c20: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4c30: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4c40: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c70: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4c80: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4ca0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cb0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4cc0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
4ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4cf0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
4d00: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
4d10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
4d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4d30: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
4d40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4d50: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
4d60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4d70: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
4d80: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4d90: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
4da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4db0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
4dc0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4dd0: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
4de0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4df0: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
4e00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4e10: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
4e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e30: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
4e40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e50: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
4e60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e70: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
4e80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e90: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
4ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4eb0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
4ec0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4ed0: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
4ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ef0: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
4f00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f10: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
4f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f30: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
4f40: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
4f50: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
4f60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f70: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f80: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
4f90: 46 31 30 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F10230}.**.** Th
4fa0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
4fb0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
4fc0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
4fd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
4fe0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
4ff0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5000: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5010: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5020: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5030: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5040: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5050: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5060: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5070: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5080: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
5090: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
50a0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
50b0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
50c0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
50d0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
50e0: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
50f0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5100: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5110: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5120: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
5130: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
5140: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  010.#define SQLI
5150: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5160: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5170: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
51b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
51c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
51d0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
51e0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
51f0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5200: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
5210: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5220: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5230: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5240: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5250: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5260: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
5280: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
5290: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
52a0: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
52b0: 61 63 74 65 72 69 73 74 69 63 73 20 7b 46 31 30  acteristics {F10
52c0: 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  240}.**.** The x
52d0: 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69  DeviceCapabiliti
52e0: 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  es method of the
52f0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5300: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
5310: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
5320: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
5330: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
5340: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
5350: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
5360: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
5370: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
5380: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
5390: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
53a0: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
53b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
53c0: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
53d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
53e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
53f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
5400: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
5410: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
5420: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
5430: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
5440: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
5450: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
5460: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
5470: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
5480: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
5490: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
54a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
54b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
54c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
54d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
54e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
54f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
5500: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
5510: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
5520: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
5530: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
5540: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
5550: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
5560: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
5570: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
5580: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
5590: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
55a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
55b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
55c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
55d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
55e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
55f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
5600: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65  xWrite()..*/.#de
5610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5620: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
5630: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5650: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
5660: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5680: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5690: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
56a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
56b0: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
56c0: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
56d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
56e0: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20  P_ATOMIC4K      
56f0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
5700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5710: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
5720: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
5730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5740: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
5750: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
5760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5770: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
5780: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
57a0: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
57b0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
57c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
57d0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
57e0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5800: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5810: 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a    0x00000400../*
5820: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
5830: 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c  le Locking Level
5840: 73 20 7b 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a  s {F10250}.**.**
5850: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
5860: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
5870: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5880: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
5890: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
58a0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
58b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
58c0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
58d0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
58e0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
58f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5900: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
5910: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
5920: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
5930: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
5950: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5970: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
5980: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
5990: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
59a0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
59b0: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
59c0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
59d0: 67 73 20 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a  gs {F10260}.**.*
59e0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
59f0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
5a00: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
5a10: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
5a20: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
5a30: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
5a40: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
5a50: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5a60: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
5a70: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
5a80: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
5a90: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
5aa0: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
5ab0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
5ac0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
5ad0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
5ae0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
5af0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
5b00: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
5b10: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
5b20: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
5b30: 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65  C_NORMAL flag me
5b40: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f  ans.** to use no
5b50: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
5b60: 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49  antics. The SQLI
5b70: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
5b80: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  g means.** to us
5b90: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
5ba0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
5bb0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
5bc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5bd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
5be0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
5bf0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
5c00: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
5c10: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
5c20: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
5c30: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
5c40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
5c60: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46  n File Handle {F
5c70: 31 31 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  11110}.**.** An 
5c80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
5c90: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
5ca0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
5cb0: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72   the OS.** inter
5cc0: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64  face layer.  Ind
5cd0: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
5ce0: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  face implementat
5cf0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5d00: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5d10: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5d20: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5d30: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5d40: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
5d50: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
5d60: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
5d70: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
5d80: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5d90: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
5da0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
5db0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
5dc0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
5dd0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
5de0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5df0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
5e00: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
5e10: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
5e20: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
5e30: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e40: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
5e50: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
5e60: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
5e70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5e80: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
5e90: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
5ea0: 64 73 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 32  ds Object {F1112
5eb0: 30 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  0}.**.** Every f
5ec0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
5ed0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
5ee0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e  xOpen method con
5ef0: 74 61 69 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  tains a pointer 
5f00: 74 6f 0a 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63  to.** an instanc
5f10: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
5f20: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  .  This object d
5f30: 65 66 69 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65  efines the.** me
5f40: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
5f50: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
5f60: 65 72 61 74 69 6f 6e 73 20 61 67 61 69 6e 73 74  erations against
5f70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
5f80: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5f90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5fa0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5fb0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
5fc0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
5fd0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
5fe0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
5ff0: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
6000: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
6010: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
6020: 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  a Mac OS-X style
6030: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
6040: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
6050: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
6060: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
6070: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6080: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6090: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
60a0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
60b0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
60c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
60d0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
60e0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
60f0: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6100: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6110: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
6120: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
6130: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
6140: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6150: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
6160: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6170: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6180: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6190: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
61a0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
61b0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
61c0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
61d0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
61e0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
61f0: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6200: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6210: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
6220: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
6230: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
6240: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
6250: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
6260: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
6270: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6280: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6290: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
62a0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
62b0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
62c0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
62d0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
62e0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
62f0: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6300: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6310: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
6320: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
6330: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
6340: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
6350: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
6360: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
6370: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6380: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6390: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
63a0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
63b0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
63c0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
63d0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
63e0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
63f0: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6400: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6410: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
6420: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
6430: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
6440: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
6450: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
6460: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
6470: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6480: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6490: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
64a0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
64b0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
64c0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
64d0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
64e0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
64f0: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6500: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6510: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
6520: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
6530: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
6540: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
6550: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
6560: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
6570: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6580: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6590: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
65a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
65b0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
65c0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
65d0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
65e0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
65f0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6600: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6610: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
6620: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
6630: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6640: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6650: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
6660: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
6670: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6680: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6690: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
66a0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
66b0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
66c0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
66d0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
66e0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
66f0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6700: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6710: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
6720: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
6730: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6740: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
6750: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
6760: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
6770: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6780: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6790: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
67a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
67b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
67c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
67d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6800: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6810: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
6820: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6830: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
6840: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6850: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
6860: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6870: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
68a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
68b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
68c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
68d0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
68e0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
68f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6900: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6910: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6920: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6930: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6940: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6950: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6960: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6970: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6980: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6990: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
69a0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
69b0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
69c0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
69d0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
69e0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
69f0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6a00: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6a10: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6a30: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6a40: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6a50: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a60: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6a70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a80: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6a90: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6aa0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6ab0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6ac0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6ad0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6ae0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6af0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6b00: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6b10: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6b20: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6b30: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6b40: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
6b50: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
6b60: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6b70: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
6b80: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
6b90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6ba0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
6bb0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
6bc0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
6bd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
6be0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6bf0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
6c00: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
6c10: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
6c20: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
6c30: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
6c40: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
6c50: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
6c60: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
6c70: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
6c80: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
6c90: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
6ca0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
6cb0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
6cc0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
6cd0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
6ce0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
6cf0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
6d00: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
6d10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
6d20: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
6d30: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
6d40: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
6d50: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
6d60: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6d70: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
6d80: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
6d90: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
6da0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
6db0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
6dc0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
6dd0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
6de0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
6df0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
6e00: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
6e10: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
6e20: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
6e30: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
6e40: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
6e50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6e60: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
6e70: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46  ntrol Opcodes {F
6e80: 31 31 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  11310}.**.** The
6e90: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
6ea0: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
6eb0: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
6ec0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
6ed0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
6ee0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6ef0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
6f00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6f10: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
6f20: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
6f30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6f40: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
6f50: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
6f60: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
6f70: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
6f80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
6f90: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
6fa0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
6fb0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
6fc0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
6fd0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
6fe0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6ff0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
7000: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
7010: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7020: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
7030: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
7040: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
7050: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
7060: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
7070: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
7080: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
7090: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
70a0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
70b0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
70c0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
70d0: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  * is defined..*/
70e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
70f0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
7100: 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20         1../*.** 
7110: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7120: 48 61 6e 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a  Handle {F17110}.
7130: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
7140: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
7150: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
7160: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
7170: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
7180: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
7190: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
71a0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
71b0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
71c0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
71d0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
71e0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
71f0: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
7200: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
7210: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
7220: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
7230: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
7240: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
7250: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
7260: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
7270: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7280: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
7290: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
72a0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
72b0: 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 46 31  rface Object {F1
72c0: 31 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  1140}.**.** An i
72d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73  nstance of the s
72e0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
72f0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
7300: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a  terface between.
7310: 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  ** the SQLite co
7320: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
7330: 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
7340: 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66  system.  The "vf
7350: 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d  s".** in the nam
7360: 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20  e of the object 
7370: 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74  stands for "virt
7380: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22  ual file system"
7390: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
73a0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
73b0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
73c0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
73d0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
73e0: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
73f0: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
7400: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
7410: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
7420: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
7430: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
7440: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
7450: 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
7460: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7470: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7480: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7490: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
74a0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
74b0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
74c0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
74d0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
74e0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
74f0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
7500: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
7510: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
7520: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
7530: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
7540: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
7550: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7560: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7570: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7580: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7590: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
75a0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
75b0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
75c0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
75d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
75e0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
75f0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
7600: 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  e list..**.** Th
7610: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
7620: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
7630: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
7640: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
7650: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
7660: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
7670: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
7680: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
7690: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
76a0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
76b0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
76c0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
76d0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
76e0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
76f0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
7700: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
7710: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
7720: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
7730: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
7740: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
7750: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
7760: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
7770: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
7780: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
7790: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
77a0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
77b0: 7b 46 31 31 31 34 31 7d 20 53 51 4c 69 74 65 20  {F11141} SQLite 
77c0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
77d0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
77e0: 65 20 73 74 72 69 6e 67 20 70 61 73 73 65 64 20  e string passed 
77f0: 74 6f 0a 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73  to.** xOpen() is
7800: 20 61 20 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65   a full pathname
7810: 20 61 73 20 67 65 6e 65 72 61 74 65 64 20 62 79   as generated by
7820: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
7830: 20 61 6e 64 0a 2a 2a 20 74 68 61 74 20 74 68 65   and.** that the
7840: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
7850: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
7860: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
7870: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
7880: 20 7b 45 4e 44 7d 20 20 53 6f 20 74 68 65 20 5b   {END}  So the [
7890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
78a0: 6e 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  n store a pointe
78b0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
78c0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
78d0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
78e0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
78f0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a  me reason..**.**
7900: 20 7b 46 31 31 31 34 32 7d 20 54 68 65 20 66 6c   {F11142} The fl
7910: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7920: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
7930: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
7940: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
7950: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7960: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
7970: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
7980: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
7990: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
79a0: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
79b0: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
79c0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
79d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
79e0: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
79f0: 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a  CREATE]. {END}.*
7a00: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
7a10: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
7a20: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
7a30: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
7a40: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
7a50: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
7a60: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
7a70: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
7a80: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  be set..**.** {F
7a90: 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77 69  11143} SQLite wi
7aa0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
7ab0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
7ac0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
7ad0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
7ae0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
7af0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
7b00: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
7b10: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7b20: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
7b30: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7b40: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
7b50: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7b60: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
7b70: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7b80: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
7b90: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7ba0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
7bb0: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
7bc0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7bd0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
7be0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7bf0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
7c00: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  ].** </ul> {END}
7c10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
7c20: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
7c30: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
7c40: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
7c50: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
7c60: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
7c70: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
7c80: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
7c90: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
7ca0: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
7cb0: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
7cc0: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
7cd0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
7ce0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
7cf0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
7d00: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
7d10: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
7d20: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
7d30: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
7d40: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
7d50: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
7d60: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
7d70: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
7d80: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
7d90: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
7da0: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
7db0: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
7dc0: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
7dd0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
7de0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
7df0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
7e00: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
7e10: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
7e20: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
7e30: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
7e40: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
7e50: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
7e60: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
7e70: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
7e80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
7e90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
7ea0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7eb0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
7ec0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b  ** </ul>.**.** {
7ed0: 46 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51 4c  F11145} The [SQL
7ee0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7ef0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
7f00: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
7f10: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
7f20: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
7f30: 65 64 2e 20 20 7b 46 31 31 31 34 36 7d 20 54 68  ed.  {F11146} Th
7f40: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
7f50: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
7f60: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
7f70: 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73   TEMP  databases
7f80: 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66  , journals and f
7f90: 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  or subjournals..
7fa0: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54  **.** {F11147} T
7fb0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
7fc0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
7fd0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
7fe0: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a  hould be opened.
7ff0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
8000: 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20 66   access.  This f
8010: 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20 61  lag is set for a
8020: 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74 0a  ll files except.
8030: 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e 20  ** for the main 
8040: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a  database file..*
8050: 2a 0a 2a 2a 20 7b 46 31 31 31 34 38 7d 20 41 74  *.** {F11148} At
8060: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
8070: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
8080: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8090: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
80a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
80b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
80c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
80d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
80e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45 4e 44 7d   to xOpen. {END}
80f0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
8100: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
8110: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
8120: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
8130: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
8140: 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20  ll it in..**.** 
8150: 7b 46 31 31 31 34 39 7d 20 54 68 65 20 66 6c 61  {F11149} The fla
8160: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8170: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8180: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8190: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
81a0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
81b0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
81c0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
81d0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
81e0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
81f0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8200: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8210: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8220: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8230: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8240: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8250: 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d 20 20 54  adable. {END}  T
8260: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
8270: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
8280: 2a 0a 2a 2a 20 7b 46 31 31 31 35 30 7d 20 53 51  *.** {F11150} SQ
8290: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
82a0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
82b0: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
82c0: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
82d0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
82e0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46  FullPathname. {F
82f0: 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63 74  11151} The exact
8300: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
8310: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8320: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
8330: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
8340: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 7b 45  oth  methods. {E
8350: 4e 44 7d 20 20 49 66 20 74 68 65 20 6f 75 74 70  ND}  If the outp
8360: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
8370: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
8380: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
8390: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
83a0: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
83b0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
83c0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
83d0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
83e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
83f0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
8400: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
8410: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
8420: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
8430: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
8440: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
8450: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
8460: 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64 20  , xSleep(), and 
8470: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
8480: 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
8490: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
84a0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
84b0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
84c0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
84d0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
84e0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
84f0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
8500: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
8510: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
8520: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
8530: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
8540: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
8550: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
8560: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
8570: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
8580: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
8590: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
85a0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
85b0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
85c0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
85d0: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
85e0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
85f0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
8600: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
8610: 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72 72  iven.  The xCurr
8620: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
8630: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
8640: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
8650: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
8660: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a  date and time..*
8670: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8680: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
8690: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
86a0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
86b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
86c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
86d0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
86e0: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
86f0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
8700: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
8710: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
8720: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
8730: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
8740: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
8750: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
8760: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
8770: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
8780: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
8790: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
87a0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
87b0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
87c0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
87d0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
87e0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
87f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
8800: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
8810: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
8820: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
8830: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
8840: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8850: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
8860: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
8870: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
8880: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
8890: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
88a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
88b0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
88c0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
88d0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
88e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
88f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8900: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
8910: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8920: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
8930: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8940: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8950: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
8960: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
8970: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
8980: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8990: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
89a0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
89b0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
89c0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
89d0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
89e0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29   void *(*xDlSym)
89f0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
8a00: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
8a10: 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69  *zSymbol);.  voi
8a20: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
8a30: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
8a40: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
8a50: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
8a60: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
8a70: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
8a80: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
8a90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
8aa0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
8ab0: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
8ac0: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
8ad0: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
8ae0: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
8af0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
8b00: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
8b10: 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  /* New fields
8b20: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
8b30: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
8b40: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
8b50: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
8b60: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
8b70: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
8b80: 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ns. */.};../*.**
8b90: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
8ba0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
8bb0: 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 46 31 31   VFS method {F11
8bc0: 31 39 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  190}.**.** {F111
8bd0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
8be0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
8bf0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
8c00: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
8c10: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
8c20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
8c30: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
8c40: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
8c50: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
8c60: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
8c70: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
8c80: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
8c90: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 46 31 31  ing for..** {F11
8ca0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
8cb0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
8cc0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
8cd0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
8ce0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8cf0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
8d00: 7b 46 31 31 31 39 33 7d 20 57 69 74 68 20 53 51  {F11193} With SQ
8d10: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8d20: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
8d30: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
8d40: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
8d50: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
8d60: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
8d70: 6c 65 2e 0a 2a 2a 20 7b 46 31 31 31 39 34 7d 20  le..** {F11194} 
8d80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
8d90: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
8da0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
8db0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
8dc0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
8dd0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
8de0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
8df0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
8e00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
8e10: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
8e20: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
8e30: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
8e40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
8e50: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
8e60: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 46 31 30  ite Library {F10
8e70: 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  130}.**.** The s
8e80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
8e90: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
8ea0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
8eb0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 70 72  QLite library pr
8ec0: 69 6f 72 20 74 6f 20 75 73 65 2e 20 20 54 68 65  ior to use.  The
8ed0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
8ee0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
8ef0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
8f00: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
8f10: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
8f20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8f30: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
8f40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
8f50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
8f60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
8f70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
8f80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
8f90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8fa0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
8fb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
8fc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
8fd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
8fe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
8ff0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9000: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
9010: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9020: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9030: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9040: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9050: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9060: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9070: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9080: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9090: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
90a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 20 20  rmless no-ops.  
90b0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
90c0: 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  ** the sqlite3_i
90d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
90e0: 69 6e 65 20 6d 61 79 20 62 65 20 63 61 6c 6c 65  ine may be calle
90f0: 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
9100: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 6f 6e 73  .** without cons
9110: 65 71 75 65 6e 63 65 2e 20 20 53 65 63 6f 6e 64  equence.  Second
9120: 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
9130: 65 76 61 6c 75 61 74 69 6f 6e 73 20 6f 66 0a 2a  evaluations of.*
9140: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
9150: 6c 69 7a 65 28 29 20 61 72 65 20 6e 6f 2d 6f 70  lize() are no-op
9160: 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  s.  The sqlite3_
9170: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
9180: 74 69 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f 72  tine.** only wor
9190: 6b 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ks the first tim
91a0: 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20 66  e it is called f
91b0: 6f 72 20 61 20 70 72 6f 63 65 73 73 2c 20 6f 72  or a process, or
91c0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 74 69   the first.** ti
91d0: 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  me it is called 
91e0: 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 68  after sqlite3_sh
91f0: 75 74 64 6f 77 6e 28 29 2e 20 20 49 6e 20 61 6c  utdown().  In al
9200: 6c 20 6f 74 68 65 72 20 63 61 73 65 73 2c 0a 2a  l other cases,.*
9210: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
9220: 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 20 53  lize() returns S
9230: 51 4c 49 54 45 5f 4f 4b 20 77 69 74 68 6f 75 74  QLITE_OK without
9240: 20 64 6f 69 6e 67 20 61 6e 79 20 72 65 61 6c 20   doing any real 
9250: 77 6f 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  work..**.** Amon
9260: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
9270: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9280: 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ze() shall invok
9290: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
92a0: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
92b0: 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ly, sqlite3_shut
92c0: 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20  down().** shall 
92d0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
92e0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  s_end()..**.** T
92f0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9300: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9310: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
9320: 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  K on success..**
9330: 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61   If for some rea
9340: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
9350: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
9360: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
9370: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
9380: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
9390: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
93a0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
93b0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
93c0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
93d0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
93e0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53  de] other than S
93f0: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
9400: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9410: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9420: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
9430: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
9440: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
9450: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
9460: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
9470: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
9480: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
9490: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
94a0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
94b0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
94c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
94d0: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
94e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
94f0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
9500: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
9510: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
9520: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
9530: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
9540: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
9550: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
9560: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
9570: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20  y.  However, if 
9580: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
9590: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
95a0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
95b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
95c0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
95d0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
95e0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
95f0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
9600: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
9610: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
9620: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
9630: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
9640: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
9650: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
9660: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
9670: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
9680: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
9690: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
96a0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
96b0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
96c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
96d0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
96e0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
96f0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
9700: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
9710: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
9720: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
9730: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
9740: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
9750: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
9760: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
9770: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9780: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49   with SQLITE_OMI
9790: 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74  T_AUTOINIT might
97a0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
97b0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
97c0: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
97d0: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
97e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
97f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
9800: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
9810: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
9820: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
9830: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
9840: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
9850: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
9860: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
9870: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
9880: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9890: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
98a0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
98b0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
98c0: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
98d0: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
98e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
98f0: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
9900: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
9910: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
9920: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
9930: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
9940: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
9950: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
9960: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
9970: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
9980: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
9990: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
99a0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
99b0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
99c0: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
99d0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
99e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
99f0: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
9a00: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
9a10: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
9a20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9a30: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
9a40: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
9a50: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
9a60: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
9a70: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
9a80: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
9a90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9aa0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
9ab0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
9ac0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
9ad0: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
9ae0: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
9af0: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
9b00: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
9b10: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
9b20: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
9b30: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
9b40: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
9b50: 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64  d for unix, wind
9b60: 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a  ows, or os/2..**
9b70: 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20   When built for 
9b80: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20  other platforms 
9b90: 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54  (using the SQLIT
9ba0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d  E_OS_OTHER=1 com
9bb0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
9bc0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
9bd0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
9be0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
9bf0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
9c00: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
9c10: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
9c20: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
9c30: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
9c40: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
9c50: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
9c60: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
9c70: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
9c80: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c   must return SQL
9c90: 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73  ITE_OK on succes
9ca0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
9cb0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
9cc0: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
9cd0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
9ce0: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
9cf0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
9d00: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
9d10: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9d20: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
9d30: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
9d40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9d50: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
9d60: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
9d70: 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20   {F10145}.**.** 
9d80: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
9d90: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
9da0: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
9db0: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
9dc0: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
9dd0: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
9de0: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
9df0: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
9e00: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
9e10: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
9e20: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
9e30: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
9e40: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
9e50: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
9e60: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
9e70: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
9e80: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
9e90: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
9ea0: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
9eb0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
9ec0: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
9ed0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
9ee0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
9ef0: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
9f00: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
9f10: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
9f20: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
9f30: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
9f40: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
9f50: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
9f60: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
9f70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
9f80: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
9f90: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
9fa0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
9fb0: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
9fc0: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
9fd0: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
9fe0: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
9ff0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a000: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
a010: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
a020: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
a030: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
a040: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f   that sqlite3_co
a050: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
a060: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
a070: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
a080: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
a090: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
a0a0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
a0b0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
a0c0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
a0d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a0e0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
a0f0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a100: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a110: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a120: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
a130: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
a140: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
a150: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
a160: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
a170: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
a180: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
a190: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
a1a0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
a1b0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
a1c0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
a1d0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
a1e0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61  nt..**.** When a
a1f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a200: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
a210: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
a220: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
a230: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
a240: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
a250: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
a260: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
a270: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
a280: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
a290: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
a2a0: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
a2b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a2c0: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
a2d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
a2e0: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
a2f0: 75 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d 0a  utines {F10155}.
a300: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
a310: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
a320: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
a330: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
a340: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
a350: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
a360: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
a370: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
a380: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
a390: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
a3a0: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
a3b0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
a3c0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
a3d0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
a3e0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
a3f0: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
a400: 33 5f 63 6f 6e 66 69 67 5d 20 77 68 65 6e 20 74  3_config] when t
a410: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
a420: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
a430: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
a440: 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74 69  LOC].  By creati
a450: 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
a460: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
a470: 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
a480: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
a490: 69 67 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  ig] during confi
a4a0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20  guration, an.** 
a4b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
a4c0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
a4d0: 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c  native memory al
a4e0: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
a4f0: 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65  em.** for SQLite
a500: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
a510: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
a520: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
a530: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
a540: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 61  ite comes with a
a550: 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
a560: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
a570: 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79 20  is.** perfectly 
a580: 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
a590: 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
a5a0: 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
a5b0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
a5c0: 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
a5d0: 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
a5e0: 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
a5f0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
a600: 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
a610: 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
a620: 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
a630: 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
a640: 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
a650: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
a660: 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
a670: 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
a680: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
a690: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
a6a0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
a6b0: 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
a6c0: 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
a6d0: 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
a6e0: 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
a6f0: 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
a700: 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
a710: 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
a720: 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
a730: 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78 52  c, xFree, and xR
a740: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20 73  ealloc methods s
a750: 68 6f 75 6c 64 20 77 6f 72 6b 20 6c 69 6b 65 20  hould work like 
a760: 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
a770: 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65 61   free(), and rea
a780: 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e 73  lloc() functions
a790: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
a7a0: 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a  rd library..**.*
a7b0: 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
a7c0: 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
a7d0: 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
a7e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
a7f0: 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
a800: 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
a810: 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
a820: 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
a830: 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
a840: 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
a850: 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
a860: 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
a870: 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
a880: 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
a890: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
a8a0: 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
a8b0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
a8c0: 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
a8d0: 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
a8e0: 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
a8f0: 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
a900: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
a910: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
a920: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a930: 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
a940: 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
a950: 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
a960: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
a970: 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
a980: 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
a990: 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a  power of 2..**.*
a9a0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
a9b0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
a9c0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
a9d0: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
a9e0: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
a9f0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
aa00: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
aa10: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
aa20: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
aa30: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
aa40: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
aa50: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
aa60: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
aa70: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
aa80: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
aa90: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
aaa0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
aab0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
aac0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
aad0: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
aae0: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
aaf0: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
ab00: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70  Shutdown..*/.typ
ab10: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
ab20: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
ab30: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
ab40: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
ab50: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
ab60: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
ab70: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
ab80: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
ab90: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
aba0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
abb0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
abc0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
abd0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
abe0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
abf0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
ac00: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
ac10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
ac20: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
ac30: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
ac40: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
ac50: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
ac60: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
ac70: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
ac80: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
ac90: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
aca0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
acb0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
acc0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
acd0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
ace0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
acf0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
ad00: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
ad10: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
ad20: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
ad30: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
ad40: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
ad50: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
ad60: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
ad70: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
ad80: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
ad90: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
ada0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
adb0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31 30  ion Options {F10
adc0: 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  160}.**.** These
add0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
ade0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
adf0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
ae00: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
ae10: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
ae20: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
ae30: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
ae40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ae50: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
ae60: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
ae70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ae80: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
ae90: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
aea0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
aeb0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
aec0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
aed0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
aee0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
aef0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
af00: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
af10: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
af20: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
af30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
af40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
af50: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
af60: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
af70: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
af80: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
af90: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
afa0: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
afb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
afc0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
afd0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
afe0: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
aff0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
b000: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
b010: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
b020: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
b030: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
b040: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b050: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
b060: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
b070: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
b080: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
b090: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
b0a0: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
b0b0: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
b0c0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b0d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
b0e0: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
b0f0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
b100: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
b110: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
b120: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
b130: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
b140: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
b150: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
b160: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
b170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
b180: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
b190: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
b1a0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
b1b0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
b1c0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
b1d0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b1e0: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
b1f0: 41 44 53 41 46 45 3d 31 29 20 74 68 65 20 53 51  ADSAFE=1) the SQ
b200: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
b210: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
b220: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
b230: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b240: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
b250: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
b260: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
b270: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
b280: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
b290: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
b2a0: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
b2b0: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
b2c0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
b2d0: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
b2e0: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
b2f0: 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ime.</dd>.**.** 
b300: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
b310: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
b320: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
b330: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
b340: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
b350: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
b360: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
b370: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
b380: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
b390: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
b3a0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
b3b0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
b3c0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
b3d0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
b3e0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
b3f0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
b400: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b410: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
b420: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
b430: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b440: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
b450: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
b460: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
b470: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
b480: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
b490: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
b4a0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
b4b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b4c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
b4d0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
b4e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
b4f0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
b500: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
b510: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
b520: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b530: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
b540: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
b550: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
b560: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
b570: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
b580: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
b590: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
b5a0: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
b5b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
b5c0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
b5d0: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
b5e0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
b5f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b600: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
b610: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
b620: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
b630: 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61  es single boolea
b640: 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  n argument which
b650: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
b660: 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  bles.** the coll
b670: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
b680: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
b690: 69 73 74 69 63 73 2e 20 20 57 68 65 6e 20 64 69  istics.  When di
b6a0: 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66  sabled, the.** f
b6b0: 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
b6c0: 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
b6d0: 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
b6e0: 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
b6f0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
b700: 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
b710: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
b720: 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
b730: 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
b740: 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
b750: 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20  ap_limit()].**  
b760: 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65   <li> sqlite3_me
b770: 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a  mory_status().**
b780: 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64     </ul>.** </dd
b790: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
b7a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
b7b0: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
b7c0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
b7d0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
b7e0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
b7f0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
b800: 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
b810: 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
b820: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
b830: 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  :  A pointer to 
b840: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a  the memory, the.
b850: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
b860: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28  scratch buffer (
b870: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
b880: 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28  ber of buffers (
b890: 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
b8a0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
b8b0: 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
b8c0: 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61  . The first.** a
b8d0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
b8e0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
b8f0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
b900: 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73  t (sz+4)*N bytes
b910: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
b920: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
b930: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
b940: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
b950: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
b960: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
b970: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
b980: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
b990: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
b9a0: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
b9b0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
b9c0: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
b9d0: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
b9e0: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
b9f0: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
ba00: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
ba10: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ba20: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
ba30: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
ba40: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
ba50: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
ba60: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
ba70: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
ba80: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
ba90: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
baa0: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
bab0: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
bac0: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
bad0: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
bae0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
baf0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
bb00: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
bb10: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bb20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
bb30: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
bb40: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
bb50: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
bb60: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
bb70: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
bb80: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
bb90: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
bba0: 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  he.  There are t
bbb0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
bbc0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
bbd0: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
bbe0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
bbf0: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
bc00: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
bc10: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
bc20: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d  he sz argument m
bc30: 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f  ust be a power o
bc40: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
bc50: 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68  2 and 32768.  Th
bc60: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
bc70: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
bc80: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
bc90: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73  n of at least (s
bca0: 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66 20  z+4)*N bytes of 
bcb0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
bcc0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
bcd0: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
bce0: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
bcf0: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
bd00: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
bd10: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
bd20: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
bd30: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
bd40: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a    If additional.
bd50: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
bd60: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
bd70: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
bd80: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
bd90: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
bda0: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
bdb0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
bdc0: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
bdd0: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
bde0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
bdf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
be00: 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
be10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
be20: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
be30: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
be40: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
be50: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
be60: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
be70: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
be80: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
be90: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
bea0: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
beb0: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
bec0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bed0: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
bee0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
bef0: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e  rguments: A poin
bf00: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
bf10: 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  y, the number of
bf20: 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
bf30: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
bf40: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
bf50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
bf60: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20 63    When.** this c
bf70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf80: 69 6f 6e 20 69 73 20 75 73 65 64 2c 20 53 51 4c  ion is used, SQL
bf90: 69 74 65 20 6e 65 76 65 72 20 63 61 6c 6c 73 20  ite never calls 
bfa0: 74 68 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d 61  the system.** ma
bfb0: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
bfc0: 61 74 69 6f 6e 20 62 75 74 20 69 6e 73 74 65 61  ation but instea
bfd0: 64 20 75 73 65 73 20 74 68 65 20 73 75 70 70 6c  d uses the suppl
bfe0: 69 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ied memory buffe
bff0: 72 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20  r.** to satisfy 
c000: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  all [sqlite3_mal
c010: 6c 6f 63 28 29 5d 20 72 65 71 75 65 73 74 73 2e  loc()] requests.
c020: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c030: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
c040: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
c050: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c060: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c070: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c080: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c090: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c0a0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
c0b0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c0c0: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
c0d0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
c0e0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
c0f0: 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
c100: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
c110: 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75   place.** the mu
c120: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
c130: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
c140: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c150: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c160: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
c170: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c180: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c190: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c1a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c1b0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c1c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
c1d0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
c1e0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
c1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c200: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
c210: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
c220: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
c230: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
c240: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
c250: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
c260: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
c270: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
c280: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
c290: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
c2a0: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
c2b0: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
c2c0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
c2d0: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
c2e0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
c2f0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
c300: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c310: 46 49 47 5f 4d 45 4d 53 59 53 33 3c 2f 64 74 3e  FIG_MEMSYS3</dt>
c320: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c330: 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
c340: 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
c350: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
c360: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
c370: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 20 73  ENABLE_MEMSYS3 s
c380: 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 20 49  ymbol defined. I
c390: 66 20 61 76 61 69 6c 61 62 6c 65 2c 20 74 68 65  f available, the
c3a0: 6e 20 69 74 20 69 73 20 75 73 65 64 0a 2a 2a 20  n it is used.** 
c3b0: 74 6f 20 69 6e 73 74 61 6c 6c 20 61 6e 20 61 6c  to install an al
c3c0: 74 65 72 6e 61 74 69 76 65 20 73 65 74 20 6f 66  ternative set of
c3d0: 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
c3e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c3f0: 69 6e 65 73 0a 2a 2a 20 6b 6e 6f 77 6e 20 61 73  ines.** known as
c400: 20 74 68 65 20 22 6d 65 6d 73 79 73 33 22 20 61   the "memsys3" a
c410: 6c 6c 6f 63 61 74 6f 72 20 28 69 6e 20 74 68 65  llocator (in the
c420: 20 73 61 6d 65 20 77 61 79 20 61 73 20 53 51 4c   same way as SQL
c430: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
c440: 43 0a 2a 2a 20 6d 61 79 20 62 65 20 75 73 65 64  C.** may be used
c450: 20 74 6f 20 69 6e 73 74 61 6c 6c 20 61 6e 20 65   to install an e
c460: 78 74 65 72 6e 61 6c 20 73 65 74 20 6f 66 20 6d  xternal set of m
c470: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c480: 20 72 6f 75 74 69 6e 65 73 29 2e 0a 2a 2a 20 54   routines)..** T
c490: 68 69 73 20 6f 70 74 69 6f 6e 73 20 6d 75 73 74  his options must
c4a0: 20 62 65 20 70 61 73 73 65 64 20 74 77 6f 20 61   be passed two a
c4b0: 72 67 75 6d 65 6e 74 73 2c 20 61 20 70 6f 69 6e  rguments, a poin
c4c0: 74 65 72 20 74 6f 20 61 20 6c 61 72 67 65 20 62  ter to a large b
c4d0: 6c 6f 62 20 6f 66 0a 2a 2a 20 61 6c 6c 6f 63 61  lob of.** alloca
c4e0: 74 65 64 20 6d 65 6d 6f 72 79 20 28 74 79 70 65  ted memory (type
c4f0: 20 63 68 61 72 2a 29 20 61 6e 64 20 74 68 65 20   char*) and the 
c500: 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f 63  size of the bloc
c510: 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 69 6e 20 62  k of memory in b
c520: 79 74 65 73 0a 2a 2a 20 28 74 79 70 65 20 69 6e  ytes.** (type in
c530: 74 29 2e 20 54 68 65 20 6d 65 6d 73 79 73 33 20  t). The memsys3 
c540: 61 6c 6c 6f 63 61 74 6f 72 20 6d 61 6e 61 67 65  allocator manage
c550: 73 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20  s this block of 
c560: 6d 65 6d 6f 72 79 20 61 6e 64 20 75 73 65 73 0a  memory and uses.
c570: 2a 2a 20 69 74 20 74 6f 20 73 61 74 69 73 66 79  ** it to satisfy
c580: 20 61 6c 6c 20 72 65 71 75 65 73 74 73 20 66 6f   all requests fo
c590: 72 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  r dynamic memory
c5a0: 20 6d 61 64 65 20 62 79 20 74 68 65 20 6c 69 62   made by the lib
c5b0: 72 61 72 79 2e 20 54 68 65 0a 2a 2a 20 63 61 6c  rary. The.** cal
c5c0: 6c 65 72 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ler must ensure 
c5d0: 74 68 61 74 20 74 68 65 20 62 6c 6f 63 6b 20 6f  that the block o
c5e0: 66 20 6d 65 6d 6f 72 79 20 72 65 6d 61 69 6e 73  f memory remains
c5f0: 20 76 61 6c 69 64 20 66 6f 72 20 61 73 20 6c 6f   valid for as lo
c600: 6e 67 0a 2a 2a 20 61 73 20 74 68 65 20 6d 65 6d  ng.** as the mem
c610: 73 79 73 33 20 61 6c 6c 6f 63 61 74 6f 72 20 69  sys3 allocator i
c620: 73 20 69 6e 20 75 73 65 2e 3c 2f 64 64 3e 0a 2a  s in use.</dd>.*
c630: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
c640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c650: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
c660: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
c670: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c680: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
c690: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
c6a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c6b0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
c6c0: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
c6d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6e0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
c6f0: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
c700: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
c710: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c720: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
c730: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
c740: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c750: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
c760: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
c770: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
c780: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
c790: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
c7a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
c7b0: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
c7c0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
c7d0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
c7e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
c7f0: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
c800: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
c810: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
c820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
c830: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
c840: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
c850: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
c860: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c870: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
c880: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
c890: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
c8a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
c8b0: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
c8c0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
c8d0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c8f0: 49 47 5f 4d 45 4d 53 59 53 33 20 20 20 20 20 20  IG_MEMSYS3      
c900: 31 32 20 20 2f 2a 20 75 38 2a 2c 20 69 6e 74 20  12  /* u8*, int 
c910: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
c920: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
c930: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
c940: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 32  esult Codes {F12
c950: 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200}.**.** The s
c960: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
c970: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
c980: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
c990: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
c9a0: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
c9b0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
c9c0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
c9d0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
c9e0: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
c9f0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
ca00: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
ca10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
ca20: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
ca30: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
ca40: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 31 7d 20  .**.** {F12201} 
ca50: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
ca60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
ca70: 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a  hall have the.**
ca80: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
ca90: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
caa0: 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c  ] feature disabl
cab0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
cac0: 2a 0a 2a 2a 20 7b 46 31 32 32 30 32 7d 20 54 68  *.** {F12202} Th
cad0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
cae0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
caf0: 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (D,F)] interface
cb00: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a   shall enable.**
cb10: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
cb20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
cb30: 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61  ] for the  [data
cb40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cb50: 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   D.**          i
cb60: 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65  f the F paramete
cb70: 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69  r is true, or di
cb80: 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20  sable them if F 
cb90: 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74  is false..*/.int
cba0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
cbb0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
cbc0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
cbd0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
cbe0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
cbf0: 74 20 52 6f 77 69 64 20 7b 46 31 32 32 32 30 7d  t Rowid {F12220}
cc00: 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72  .**.** Each entr
cc10: 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
cc20: 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
cc30: 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
cc40: 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
cc50: 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69 64  alled the "rowid
cc60: 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ". The rowid is 
cc70: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
cc80: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
cc90: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
cca0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
ccb0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
ccc0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
ccd0: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
cce0: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
ccf0: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
cd00: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74  mns. If.** the t
cd10: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
cd20: 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47 45  n of type INTEGE
cd30: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74 68  R PRIMARY KEY th
cd40: 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
cd50: 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
cd60: 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
cd70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
cd80: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
cd90: 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d 6f   rowid of the mo
cda0: 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
cdb0: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 69  cessful INSERT i
cdc0: 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
cdd0: 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
cde0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
cdf0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
ce00: 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f  argument.  If no
ce10: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
ce20: 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  RTs.** have ever
ce30: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
ce40: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
ce50: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
ce60: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
ce70: 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63 63 75  f an INSERT occu
ce80: 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
ce90: 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 6f  ger, then the ro
cea0: 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65 72  wid of the inser
ceb0: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
cec0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
ced0: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
cee0: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
cef0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
cf00: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
cf10: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
cf20: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
cf30: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
cf40: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
cf50: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
cf60: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
cf70: 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
cf80: 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45 52 54  .**.** An INSERT
cf90: 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
cfa0: 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
cfb0: 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
cfc0: 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
cfd0: 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f 65 73   INSERT and does
cfe0: 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
cff0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
d000: 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
d010: 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
d020: 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
d030: 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
d040: 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
d050: 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
d060: 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
d070: 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
d080: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
d090: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
d0a0: 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
d0b0: 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
d0c0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
d0d0: 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
d0e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
d0f0: 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
d100: 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
d110: 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
d120: 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
d130: 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
d140: 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
d150: 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
d160: 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
d170: 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
d180: 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
d190: 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
d1a0: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
d1b0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
d1c0: 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
d1d0: 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
d1e0: 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20 63 6f   an INSERT is co
d1f0: 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
d200: 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
d210: 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
d220: 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
d230: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
d240: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
d250: 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2221} The [sqlit
d260: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
d270: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e  owid()] function
d280: 20 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77   returns the row
d290: 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  id.**          o
d2a0: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
d2b0: 74 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  t successful INS
d2c0: 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e  ERT performed on
d2d0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
d2e0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
d2f0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
d300: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
d310: 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a  or higher level.
d320: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
d330: 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
d340: 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
d350: 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69  ve been no quali
d360: 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e 0a 2a  fying inserts..*
d370: 2a 0a 2a 2a 20 7b 46 31 32 32 32 33 7d 20 54 68  *.** {F12223} Th
d380: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
d390: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
d3a0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
d3b0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
d3c0: 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65 6e   same value when
d3d0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
d3e0: 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63 6f   same trigger co
d3f0: 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20  ntext.**        
d400: 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65    immediately be
d410: 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20 61  fore and after a
d420: 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a   ROLLBACK..**.**
d430: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
d440: 0a 2a 2a 20 7b 55 31 32 32 33 32 7d 20 49 66 20  .** {U12232} If 
d450: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
d460: 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
d470: 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65 20 73   INSERT on the s
d480: 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
d490: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d4a0: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
d4b0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
d4c0: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20  rt_rowid()].**  
d4d0: 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
d4e0: 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
d4f0: 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
d500: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
d510: 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  id,.**          
d520: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
d530: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
d540: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d550: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20  rowid()] is.**  
d560: 20 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63          unpredic
d570: 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
d580: 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
d590: 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
d5a0: 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
d5b0: 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
d5c0: 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  d..*/.sqlite3_in
d5d0: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
d5e0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
d5f0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
d600: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
d610: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
d620: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32  ws Modified {F12
d630: 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  240}.**.** This 
d640: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
d650: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
d660: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
d670: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
d680: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
d690: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
d6a0: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
d6b0: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
d6c0: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
d6d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d6e0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
d6f0: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
d700: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20  ameter..** Only 
d710: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
d720: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
d730: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
d740: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72  T, UPDATE,.** or
d750: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
d760: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
d770: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
d780: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
d790: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
d7a0: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
d7b0: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
d7c0: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
d7d0: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
d7e0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
d7f0: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
d800: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
d810: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
d820: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68  .**.** A "row ch
d830: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
d840: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
d850: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
d860: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
d870: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
d880: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
d890: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
d8a0: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
d8b0: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
d8c0: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  ts of REPLACE co
d8d0: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
d8e0: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
d8f0: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
d900: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20  ng, DROP TABLE, 
d910: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
d920: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
d930: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
d940: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
d950: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
d960: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
d970: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
d980: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
d990: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
d9a0: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
d9b0: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20   trigger.  Most 
d9c0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
d9d0: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
d9e0: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
d9f0: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
da00: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
da10: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
da20: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
da30: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
da40: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
da50: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
da60: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
da70: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
da80: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
da90: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
daa0: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
dab0: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
dac0: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
dad0: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
dae0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
daf0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
db00: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
db10: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
db20: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
db30: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
db40: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
db50: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
db60: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
db70: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
db80: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
db90: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
dba0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
dbb0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
dbc0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
dbd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68  ..**.** Thus, wh
dbe0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
dbf0: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
dc00: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
dc10: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
dc20: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
dc30: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
dc40: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
dc50: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
dc60: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
dc70: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
dc80: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  .  Within the bo
dc90: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
dca0: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
dcb0: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
dcc0: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
dcd0: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
dce0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
dcf0: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
dd00: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
dd10: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
dd20: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
dd30: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
dd40: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
dd50: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
dd60: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
dd70: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
dd80: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
dd90: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
dda0: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
ddb0: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
ddc0: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
ddd0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
dde0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
ddf0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
de00: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
de10: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
de20: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
de30: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
de40: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
de50: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
de60: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
de70: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
de80: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
de90: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
dea0: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
deb0: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
dec0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
ded0: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
dee0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
def0: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
df00: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
df10: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
df20: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
df30: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
df40: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
df50: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
df60: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
df70: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
df80: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
df90: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
dfa0: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
dfb0: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
dfc0: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
dfd0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
dfe0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
dff0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
e000: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
e010: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ad..**.** INVARI
e020: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
e030: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  241} The [sqlite
e040: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  3_changes()] fun
e050: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75  ction shall retu
e060: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
e070: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77  .**          row
e080: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
e090: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
e0a0: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
e0b0: 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  E,.**          o
e0c0: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
e0d0: 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  nt on the same d
e0e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e0f0: 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
e100: 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61     within the sa
e110: 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69  me or higher tri
e120: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
e130: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
e140: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
e150: 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61  not been any qua
e160: 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e  lifying row chan
e170: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ges..**.** {F122
e180: 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  43} Statements o
e190: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
e1a0: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
e1b0: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
e1c0: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
e1d0: 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20  use shall cause 
e1e0: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
e1f0: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
e200: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
e210: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65  ()] to return ze
e220: 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ro, regardless o
e230: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
e240: 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73    number of rows
e250: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
e260: 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  he table..**.** 
e270: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
e280: 2a 2a 20 7b 55 31 32 32 35 32 7d 20 49 66 20 61  ** {U12252} If a
e290: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
e2a0: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
e2b0: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
e2c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
e2d0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
e2e0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
e2f0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
e300: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
e310: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
e320: 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74      is unpredict
e330: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
e340: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
e350: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
e360: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
e370: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
e380: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
e390: 20 4d 6f 64 69 66 69 65 64 20 7b 46 31 32 32 36   Modified {F1226
e3a0: 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0}.**.** This fu
e3b0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
e3c0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
e3d0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
e3e0: 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50  by INSERT,.** UP
e3f0: 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
e400: 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
e410: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
e420: 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
e430: 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75  ened..** The cou
e440: 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  nt includes all 
e450: 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c  changes from all
e460: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e470: 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s.  However,.** 
e480: 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
e490: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
e4a0: 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
e4b0: 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e  ment REPLACE con
e4c0: 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
e4d0: 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
e4e0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
e4f0: 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f  r DROP table pro
e500: 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20  cessing..** The 
e510: 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
e520: 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
e530: 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
e540: 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a  t makes them is.
e550: 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  ** completed (wh
e560: 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
e570: 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65   handle is passe
e580: 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
e590: 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
e5a0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
e5b0: 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
e5c0: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
e5d0: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
e5e0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
e5f0: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
e600: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
e610: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
e620: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
e630: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
e640: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
e650: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
e660: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
e670: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
e680: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
e690: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
e6a0: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
e6b0: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
e6c0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
e6d0: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
e6e0: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
e6f0: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
e700: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
e710: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
e720: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e730: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
e740: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
e750: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
e760: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
e770: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
e780: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
e790: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
e7a0: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
e7b0: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
e7c0: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
e7d0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
e7e0: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
e7f0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ad..**.** See al
e800: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
e810: 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
e820: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  face..**.** INVA
e830: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
e840: 31 32 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69  12261} The [sqli
e850: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
e860: 73 28 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  s()] returns the
e870: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a   total number.**
e880: 20 20 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77            of row
e890: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
e8a0: 62 79 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  by INSERT, UPDAT
e8b0: 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45  E, and/or DELETE
e8c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
e8d0: 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73  tements on the s
e8e0: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
e8f0: 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e  nnection], in an
e900: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  y.**          tr
e910: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73  igger context, s
e920: 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
e930: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
e940: 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   created..**.** 
e950: 7b 46 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65  {F12263} Stateme
e960: 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  nts of the form 
e970: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e980: 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a  lename" with no.
e990: 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52  **          WHER
e9a0: 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e  E clause shall n
e9b0: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
e9c0: 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
e9d0: 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
e9e0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e9f0: 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  es()]..**.** LIM
ea00: 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
ea10: 7b 55 31 32 32 36 34 7d 20 49 66 20 61 20 73 65  {U12264} If a se
ea20: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
ea30: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
ea40: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
ea50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
ea60: 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
ea70: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
ea80: 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
ea90: 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
eaa0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
eab0: 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
eac0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
ead0: 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
eae0: 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
eaf0: 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
eb00: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
eb10: 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
eb20: 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
eb30: 65 72 79 20 7b 46 31 32 32 37 30 7d 0a 2a 2a 0a  ery {F12270}.**.
eb40: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
eb50: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
eb60: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
eb70: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
eb80: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
eb90: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
eba0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
ebb0: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
ebc0: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
ebd0: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
ebe0: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
ebf0: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
ec00: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
ec10: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
ec20: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
ec30: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
ec40: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
ec50: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
ec60: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
ec70: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
ec80: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
ec90: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
eca0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
ecb0: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
ecc0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
ecd0: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
ece0: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
ecf0: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
ed00: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
ed10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ed20: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
ed30: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
ed40: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
ed50: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
ed60: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
ed70: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
ed80: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
ed90: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
eda0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
edb0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
edc0: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
edd0: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
ede0: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
edf0: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
ee00: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
ee10: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
ee20: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
ee30: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
ee40: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
ee50: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
ee60: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
ee70: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
ee80: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
ee90: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
eea0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
eeb0: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
eec0: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
eed0: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
eee0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
eef0: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
ef00: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
ef10: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
ef20: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
ef30: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ef40: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
ef50: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
ef60: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
ef70: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
ef80: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
ef90: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
efa0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
efb0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 31  S:.**.** {F12271
efc0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  } The [sqlite3_i
efd0: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65  nterrupt()] inte
efe0: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65  rface will force
eff0: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20   all running.** 
f000: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
f010: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
f020: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
f030: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f040: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
f050: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70   to halt after p
f060: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73  rocessing at mos
f070: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  t one additional
f080: 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
f090: 0a 2a 2a 20 7b 46 31 32 32 37 32 7d 20 41 6e 79  .** {F12272} Any
f0a0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
f0b0: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
f0c0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
f0d0: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
f0e0: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
f0f0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
f100: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4c 49  RRUPT]..**.** LI
f110: 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  MITATIONS:.**.**
f120: 20 7b 55 31 32 32 37 39 7d 20 49 66 20 74 68 65   {U12279} If the
f130: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f140: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
f150: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
f160: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
f170: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
f180: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
f190: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
f1a0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
f1b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
f1c0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
f1d0: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
f1e0: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
f1f0: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
f200: 74 65 20 7b 46 31 30 35 31 30 7d 0a 2a 2a 0a 2a  te {F10510}.**.*
f210: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
f220: 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
f230: 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
f240: 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
f250: 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
f260: 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
f270: 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
f280: 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
f290: 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
f2a0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
f2b0: 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
f2c0: 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
f2d0: 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
f2e0: 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
f2f0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
f300: 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
f310: 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
f320: 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
f330: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
f340: 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
f350: 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
f360: 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
f370: 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
f380: 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
f390: 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
f3a0: 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
f3b0: 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
f3c0: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
f3d0: 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
f3e0: 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
f3f0: 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
f400: 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
f410: 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
f420: 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
f430: 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
f440: 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
f450: 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
f460: 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
f470: 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
f480: 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
f490: 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
f4a0: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
f4b0: 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
f4c0: 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
f4d0: 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
f4e0: 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
f4f0: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
f500: 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
f510: 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
f520: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f530: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 31 31  S:.**.** {F10511
f540: 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  } The sqlite3_co
f550: 6d 70 6c 65 74 65 28 29 20 61 6e 64 20 73 71 6c  mplete() and sql
f560: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
f570: 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 20  ) functions.**  
f580: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 74          return t
f590: 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
f5a0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
f5b0: 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65  e last non-white
f5c0: 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  space.**        
f5d0: 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72    token in their
f5e0: 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69   input is a semi
f5f0: 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  colon that is no
f600: 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  t in between.** 
f610: 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45 47           the BEG
f620: 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20  IN and END of a 
f630: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
f640: 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
f650: 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
f660: 2a 2a 20 7b 55 31 30 35 31 32 7d 20 54 68 65 20  ** {U10512} The 
f670: 69 6e 70 75 74 20 74 6f 20 73 71 6c 69 74 65 33  input to sqlite3
f680: 5f 63 6f 6d 70 6c 65 74 65 28 29 20 6d 75 73 74  _complete() must
f690: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
f6a0: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
f6b0: 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
f6c0: 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 33 7d 20 54  **.** {U10513} T
f6d0: 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c 69  he input to sqli
f6e0: 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
f6f0: 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
f700: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
f710: 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73 74         UTF-16 st
f720: 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
f730: 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
f740: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f750: 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
f760: 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
f770: 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
f780: 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
f790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
f7a0: 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
f7b0: 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
f7c0: 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 20  ITE_BUSY Errors 
f7d0: 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12310}.**.** T
f7e0: 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
f7f0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
f800: 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
f810: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
f820: 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
f830: 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
f840: 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
f850: 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
f860: 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
f870: 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
f880: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  .**.** If the bu
f890: 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
f8a0: 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
f8b0: 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
f8c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
f8d0: 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
f8e0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
f8f0: 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
f900: 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20  he lock. If the 
f910: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
f920: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
f930: 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
f940: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
f950: 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
f960: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ts..**.** The fi
f970: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
f980: 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
f990: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
f9a0: 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
f9b0: 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
f9c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f9d0: 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
f9e0: 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  r().  The second
f9f0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
fa00: 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  the handler call
fa10: 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
fa20: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
fa30: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fa40: 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
fa50: 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
fa60: 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49  ocking event.  I
fa70: 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
fa80: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
fa90: 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
faa0: 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
fab0: 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
fac0: 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
fad0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
fae0: 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
faf0: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
fb00: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
fb10: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
fb20: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
fb30: 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
fb40: 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
fb50: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
fb60: 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
fb70: 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
fb80: 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
fb90: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
fba0: 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
fbb0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
fbc0: 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
fbd0: 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
fbe0: 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
fbf0: 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69  tention. If SQLi
fc00: 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
fc10: 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
fc20: 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
fc30: 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
fc40: 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
fc50: 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
fc60: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
fc70: 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
fc80: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
fc90: 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
fca0: 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
fcb0: 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
fcc0: 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
fcd0: 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
fce0: 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
fcf0: 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
fd00: 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
fd10: 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
fd20: 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
fd30: 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
fd40: 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
fd50: 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
fd60: 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
fd70: 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
fd80: 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
fd90: 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
fda0: 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
fdb0: 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
fdc0: 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
fdd0: 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
fde0: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
fdf0: 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
fe00: 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
fe10: 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
fe20: 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
fe30: 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
fe40: 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
fe50: 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
fe60: 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
fe70: 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
fe80: 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
fe90: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
fea0: 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
feb0: 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
fec0: 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
fed0: 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
fee0: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
fef0: 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
ff00: 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
ff10: 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
ff20: 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
ff30: 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
ff40: 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
ff50: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
ff60: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
ff70: 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
ff80: 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
ff90: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
ffa0: 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
ffb0: 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
ffc0: 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
ffd0: 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
ffe0: 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
fff0: 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
10000 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
10010 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
10020 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
10030 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
10040 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
10050 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
10060 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
10070 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
10080 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
10090 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
100a0 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
100b0 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
100c0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
100d0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
100e0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
100f0 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
10100 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
10110 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
10120 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
10130 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
10140 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
10150 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
10160 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
10170 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
10180 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
10190 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
101a0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
101b0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
101c0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
101d0 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
101e0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
101f0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
10200 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
10210 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
10220 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
10230 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
10240 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
10250 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
10260 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
10270 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
10280 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
10290 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
102a0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
102b0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
102c0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
102d0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
102e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
102f0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
10300 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
10310 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
10320 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
10330 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
10340 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
10350 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65  t handler.  Note
10360 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
10370 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
10380 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
10390 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
103a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
103b0 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  r..**.** INVARIA
103c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  NTS:.**.** {F123
103d0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
103e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
103f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
10400 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
10410 6c 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ler.**          
10420 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20  callback in the 
10430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10440 69 6f 6e 20 69 64 65 6e 74 69 66 69 65 64 20 62  ion identified b
10450 79 20 74 68 65 20 31 73 74 0a 2a 2a 20 20 20 20  y the 1st.**    
10460 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
10470 77 69 74 68 20 61 20 6e 65 77 20 62 75 73 79 20  with a new busy 
10480 68 61 6e 64 6c 65 72 20 69 64 65 6e 74 69 66 69  handler identifi
10490 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 61 6e  ed by the 2nd an
104a0 64 20 33 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  d 3rd.**        
104b0 20 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a    parameters..**
104c0 0a 2a 2a 20 7b 46 31 32 33 31 32 7d 20 54 68 65  .** {F12312} The
104d0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 68 61   default busy ha
104e0 6e 64 6c 65 72 20 66 6f 72 20 6e 65 77 20 64 61  ndler for new da
104f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10500 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ns is NULL..**.*
10510 2a 20 7b 46 31 32 33 31 34 7d 20 57 68 65 6e 20  * {F12314} When 
10520 74 77 6f 20 6f 72 20 6d 6f 72 65 20 64 61 74 61  two or more data
10530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
10540 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20  share a.**      
10550 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61      [sqlite3_ena
10560 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
10570 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d   | common cache]
10580 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
10590 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
105a0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
105b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
105c0 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
105d0 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
105e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
105f0 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
10600 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
10610 0a 2a 2a 20 7b 46 31 32 33 31 36 7d 20 49 66 20  .** {F12316} If 
10620 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
10630 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
10640 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
10650 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
10660 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
10670 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
10680 63 6b 69 6e 67 20 65 76 65 6e 74 20 77 69 6c 6c  cking event will
10690 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
106a0 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  BUSY]..**.** {F1
106b0 32 33 31 38 7d 20 53 51 4c 69 74 65 20 77 69 6c  2318} SQLite wil
106c0 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75  l invokes the bu
106d0 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20  sy handler with 
106e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68  two arguments wh
106f0 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ich.**          
10700 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  are a copy of th
10710 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69  e pointer suppli
10720 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61  ed by the 3rd pa
10730 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
10740 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
10750 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20  busy_handler()] 
10760 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74  and a count of t
10770 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69  he number of pri
10780 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  or.**          i
10790 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
107a0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
107b0 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
107c0 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a  ing event..**.**
107d0 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
107e0 0a 2a 2a 20 7b 55 31 32 33 31 39 7d 20 41 20 62  .** {U12319} A b
107f0 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 6f 75  usy handler shou
10800 6c 64 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  ld not close the
10810 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10820 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
10830 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
10840 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
10850 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
10860 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
10870 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10880 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
10890 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
108a0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
108b0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
108c0 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 46 31  Busy Timeout {F1
108d0 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2340}.**.** This
108e0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
108f0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10900 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
10910 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
10920 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
10930 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
10940 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
10950 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65   is locked.  The
10960 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
10970 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
10980 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
10990 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
109a0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
109b0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
109c0 75 6c 61 74 65 64 2e 20 7b 46 31 32 33 34 33 7d  ulated. {F12343}
109d0 20 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c   After "ms" mill
109e0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
109f0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
10a00 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
10a10 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
10a20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
10a30 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
10a40 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
10a50 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
10a60 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  ]..**.** Calling
10a70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
10a80 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
10a90 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
10aa0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
10ab0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
10ac0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
10ad0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
10ae0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
10af0 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
10b00 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
10b10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10b20 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
10b30 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
10b40 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
10b50 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
10b60 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
10b70 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
10b80 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
10b90 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
10ba0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
10bb0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
10bc0 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  leared..**.** IN
10bd0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
10be0 7b 46 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71  {F12341} The [sq
10bf0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
10c00 75 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 6f  ut()] function o
10c10 76 65 72 72 69 64 65 73 20 61 6e 79 20 70 72 69  verrides any pri
10c20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
10c30 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
10c40 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eout()] or [sqli
10c50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
10c60 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20  ()] setting.**  
10c70 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
10c80 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
10c90 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nection..**.** {
10ca0 46 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32  F12343} If the 2
10cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
10cc0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
10cd0 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73  meout()] is less
10ce0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
10cf0 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65    or equal to ze
10d00 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73  ro, then the bus
10d10 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
10d20 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a 20  ared so that.** 
10d30 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75 62           all sub
10d40 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67 20  sequent locking 
10d50 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74 65  events immediate
10d60 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ly return [SQLIT
10d70 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
10d80 46 31 32 33 34 34 7d 20 49 66 20 74 68 65 20 32  F12344} If the 2
10d90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
10da0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
10db0 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70 6f  meout()] is a po
10dc0 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
10dd0 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68 65     number N, the
10de0 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  n a busy handler
10df0 20 69 73 20 73 65 74 20 74 68 61 74 20 72 65 70   is set that rep
10e00 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a  eatedly calls.**
10e10 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53            the xS
10e20 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e  leep() method in
10e30 20 74 68 65 20 56 46 53 20 69 6e 74 65 72 66 61   the VFS interfa
10e40 63 65 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  ce until either 
10e50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
10e60 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75  lock clears or u
10e70 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74  ntil the cumulat
10e80 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 20 72  ive sleep time r
10e90 65 70 6f 72 74 65 64 20 62 61 63 6b 0a 2a 2a 20  eported back.** 
10ea0 20 20 20 20 20 20 20 20 20 62 79 20 78 53 6c 65           by xSle
10eb0 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d  ep() exceeds N m
10ec0 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a  illiseconds..*/.
10ed0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
10ee0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
10ef0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
10f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10f10 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
10f20 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
10f30 65 72 69 65 73 20 7b 46 31 32 33 37 30 7d 0a 2a  eries {F12370}.*
10f40 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
10f50 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
10f60 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
10f70 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
10f80 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
10f90 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
10fa0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
10fb0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
10fc0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
10fd0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
10fe0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
10ff0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
11000 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
11010 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
11020 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
11030 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
11040 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
11050 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
11060 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
11070 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
11080 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
11090 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
110a0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
110b0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
110c0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
110d0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
110e0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
110f0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
11100 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
11110 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
11120 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
11130 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
11140 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
11150 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
11160 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
11170 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
11180 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
11190 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
111a0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
111b0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
111c0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
111d0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
111e0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
111f0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
11200 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
11210 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
11220 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
11230 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
11240 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
11250 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
11260 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
11270 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
11280 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
11290 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
112a0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
112b0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
112c0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
112d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
112e0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
112f0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
11300 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
11310 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
11320 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
11330 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
11340 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
11350 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
11360 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
11370 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d  **.** As an exam
11380 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
11390 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
113a0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
113b0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
113c0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
113d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
113e0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
113f0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
11400 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
11410 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
11420 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
11430 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
11440 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
11450 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
11460 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
11470 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
11480 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
11490 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
114a0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
114b0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
114c0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
114d0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
114e0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
114f0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
11500 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
11510 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
11520 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
11530 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
11540 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
11550 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
11560 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
11570 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
11580 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
11590 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
115a0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
115b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
115c0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
115d0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
115e0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
115f0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
11600 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
11610 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
11620 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
11630 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
11640 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11650 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
11660 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11670 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
11680 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
11690 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
116a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
116b0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
116c0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
116d0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
116e0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
116f0 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
11700 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
11710 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
11720 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
11730 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75  ameter.  It retu
11740 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
11750 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
11760 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
11770 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
11780 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
11790 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
117a0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
117b0 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
117c0 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61   it should.** pa
117d0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ss the pointer t
117e0 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  o the result tab
117f0 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  le to sqlite3_fr
11800 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
11810 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
11820 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
11830 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
11840 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
11850 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
11860 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
11870 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
11880 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11890 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
118a0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
118b0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
118c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
118d0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
118e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
118f0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
11900 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
11910 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
11920 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
11930 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
11940 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
11950 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
11960 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
11970 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
11980 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
11990 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
119a0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
119b0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
119c0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
119d0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
119e0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
119f0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
11a00 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
11a10 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
11a20 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
11a30 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
11a40 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
11a50 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
11a60 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
11a70 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
11a80 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
11a90 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
11aa0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
11ab0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
11ac0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
11ad0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
11ae0 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  sg()]..**.** INV
11af0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
11b00 46 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71  F12371} If a [sq
11b10 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
11b20 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72  )] fails a memor
11b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  y allocation, th
11b40 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  en.**          i
11b50 74 20 66 72 65 65 73 20 74 68 65 20 72 65 73 75  t frees the resu
11b60 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
11b70 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
11b80 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
11b90 20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f      query in pro
11ba0 63 65 73 73 2c 20 73 6b 69 70 73 20 61 6e 79 20  cess, skips any 
11bb0 73 75 62 73 65 71 75 65 6e 74 20 71 75 65 72 69  subsequent queri
11bc0 65 73 2c 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  es, sets the.** 
11bd0 20 20 20 20 20 20 20 20 20 2a 72 65 73 75 6c 74           *result
11be0 70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72  p output pointer
11bf0 20 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74   to NULL and ret
11c00 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  urns [SQLITE_NOM
11c10 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  EM]..**.** {F123
11c20 37 33 7d 20 49 66 20 74 68 65 20 6e 63 6f 6c 75  73} If the ncolu
11c30 6d 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  mn parameter to 
11c40 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
11c50 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
11c60 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
11c70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  en [sqlite3_get_
11c80 74 61 62 6c 65 28 29 5d 20 77 72 69 74 65 73 20  table()] writes 
11c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
11ca0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
11cb0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
11cc0 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
11cd0 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75 6d 6e 20 69   into *ncolumn i
11ce0 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a 2a  f the query is.*
11cf0 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63 65  *          succe
11d00 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66 75  ssful (if the fu
11d10 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 53  nction returns S
11d20 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a  QLITE_OK)..**.**
11d30 20 7b 46 31 32 33 37 34 7d 20 49 66 20 74 68 65   {F12374} If the
11d40 20 6e 72 6f 77 20 70 61 72 61 6d 65 74 65 72 20   nrow parameter 
11d50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
11d60 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
11d70 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
11d80 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 67   then [sqlite3_g
11d90 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69 74  et_table()] writ
11da0 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  es the number of
11db0 20 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20   rows in the.** 
11dc0 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
11dd0 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
11de0 20 69 6e 74 6f 20 2a 6e 72 6f 77 20 69 66 20 74   into *nrow if t
11df0 68 65 20 71 75 65 72 79 20 69 73 0a 2a 2a 20 20  he query is.**  
11e00 20 20 20 20 20 20 20 20 73 75 63 63 65 73 73 66          successf
11e10 75 6c 20 28 69 66 20 74 68 65 20 66 75 6e 63 74  ul (if the funct
11e20 69 6f 6e 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ion returns SQLI
11e30 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK)..**.** {F
11e40 31 32 33 37 36 7d 20 54 68 65 20 5b 73 71 6c 69  12376} The [sqli
11e50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11e60 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 69   function sets i
11e70 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20 76 61 6c 75  ts *ncolumn valu
11e80 65 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  e to the.**     
11e90 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 63       number of c
11ea0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
11eb0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
11ec0 71 75 65 72 79 20 69 6e 20 74 68 65 20 73 71 6c  query in the sql
11ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
11ee0 61 6d 65 74 65 72 2c 20 6f 72 20 74 6f 20 7a 65  ameter, or to ze
11ef0 72 6f 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ro if the query 
11f00 69 6e 20 73 71 6c 20 68 61 73 20 61 6e 20 65 6d  in sql has an em
11f10 70 74 79 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  pty result set..
11f20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
11f30 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
11f40 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20  te3*,           
11f50 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
11f60 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
11f70 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
11f80 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
11f90 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
11fa0 72 20 2a 2a 2a 70 52 65 73 75 6c 74 2c 20 20 20  r ***pResult,   
11fb0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
11fc0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
11fd0 69 6e 74 20 2a 6e 72 6f 77 2c 20 20 20 20 20 20  int *nrow,      
11fe0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
11ff0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
12000 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
12010 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 20 20   int *ncolumn,  
12020 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
12030 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
12040 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
12050 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
12060 73 67 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72  sg         /* Er
12070 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
12080 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
12090 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
120a0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
120b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
120c0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
120d0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
120e0 6e 63 74 69 6f 6e 73 20 7b 46 31 37 34 30 30 7d  nctions {F17400}
120f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12100 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
12110 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
12120 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
12130 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
12140 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12150 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
12160 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
12170 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
12180 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
12190 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
121a0 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
121b0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
121c0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
121d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
121e0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
121f0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
12200 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
12210 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
12220 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
12230 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
12240 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
12250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
12260 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12270 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
12280 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
12290 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
122a0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
122b0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
122c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
122d0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
122e0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
122f0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
12300 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12310 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
12320 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
12330 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
12340 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
12350 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12360 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
12370 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
12380 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12390 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
123a0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
123b0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
123c0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
123d0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
123e0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
123f0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
12400 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
12410 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
12420 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
12430 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12440 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12450 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12460 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12470 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12480 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12490 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
124a0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
124b0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
124c0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
124d0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
124e0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
124f0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
12500 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
12510 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
12520 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
12530 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
12540 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
12550 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
12560 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12570 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
12580 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
12590 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
125a0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
125b0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
125c0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
125d0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
125e0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
125f0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
12600 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
12610 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
12620 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
12630 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
12640 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
12650 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
12660 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
12670 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
12680 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
12690 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
126a0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
126b0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
126c0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
126d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
126e0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
126f0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
12700 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
12710 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
12720 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
12730 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
12740 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
12750 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
12760 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
12770 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
12780 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
12790 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
127a0 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
127b0 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
127c0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
127d0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
127e0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
127f0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
12800 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
12810 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
12820 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
12830 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
12840 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
12850 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
12860 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
12870 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
12880 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
12890 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
128a0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
128b0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
128c0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
128d0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
128e0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
128f0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
12900 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
12910 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
12920 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
12930 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
12940 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
12950 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12960 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
12970 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
12980 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
12990 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
129a0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
129b0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
129c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
129d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
129e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
129f0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
12a00 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
12a10 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
12a20 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
12a30 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
12a40 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
12a50 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
12a60 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
12a70 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
12a80 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12a90 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
12aa0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
12ab0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
12ac0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
12ad0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
12ae0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
12af0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
12b00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
12b10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
12b20 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
12b30 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
12b40 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
12b50 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
12b60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12b70 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
12b80 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
12b90 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
12ba0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
12bb0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
12bc0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
12bd0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
12be0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12bf0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
12c00 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
12c10 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
12c20 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12c30 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
12c40 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
12c50 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
12c60 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
12c70 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
12c80 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
12c90 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
12ca0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
12cb0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
12cc0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
12cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
12ce0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
12cf0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
12d00 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
12d10 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
12d20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
12d30 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
12d40 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
12d50 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
12d60 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
12d70 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
12d80 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
12d90 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
12da0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
12db0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
12dc0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
12dd0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
12de0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
12df0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
12e00 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12e10 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
12e20 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
12e30 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
12e40 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
12e50 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
12e60 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
12e70 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
12e80 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
12e90 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
12ea0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12eb0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
12ec0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
12ed0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
12ee0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
12ef0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
12f00 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
12f10 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
12f20 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
12f30 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
12f40 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
12f50 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
12f60 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
12f70 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
12f80 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
12f90 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
12fa0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
12fb0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
12fc0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
12fd0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
12fe0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
12ff0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
13000 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13010 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20 20 54  *.** {F17403}  T
13020 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  he [sqlite3_mpri
13030 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ntf()] and [sqli
13040 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20  te3_vmprintf()] 
13050 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20  interfaces.**   
13060 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65          return e
13070 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74  ither pointers t
13080 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
13090 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
130a0 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20  held in.**      
130b0 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61       memory obta
130c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
130d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
130e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66  NULL pointers if
130f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
13100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
13110 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73  _malloc()] fails
13120 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 36 7d  ..**.** {F17406}
13130 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
13140 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
13150 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65  face writes a ze
13160 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
13170 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38             UTF-8
13180 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
13190 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
131a0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
131b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
131c0 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64          provided
131d0 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20   that the first 
131e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65  parameter is gre
131f0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a  ater than zero..
13200 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d 20 20  **.** {F17407}  
13210 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
13220 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
13230 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ce does not writ
13240 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  e slots of.**   
13250 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
13260 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
13270 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
13280 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
13290 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
132a0 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
132b0 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
132c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
132d0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
132e0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
132f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
13300 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
13310 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
13320 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
13330 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61  fication..*/.cha
13340 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
13350 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
13360 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
13370 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
13380 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
13390 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
133a0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
133b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
133c0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
133d0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
133e0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
133f0 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a 2a 0a  tem {F17300}.**.
13400 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
13410 72 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74  re  uses these t
13420 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
13430 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
13440 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
13450 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
13460 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
13470 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
13480 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
13490 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
134a0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
134b0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
134c0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
134d0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
134e0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
134f0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
13500 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
13510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13520 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
13530 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
13540 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
13550 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
13560 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
13570 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
13580 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
13590 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  er..** If sqlite
135a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
135b0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
135c0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
135d0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
135e0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
135f0 74 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72  ter.  If the par
13600 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
13610 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13620 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
13630 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
13640 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
13650 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
13660 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69  ter..**.** Calli
13670 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
13680 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
13690 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
136a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
136b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
136c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
136d0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
136e0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
136f0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
13700 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  sed.  The sqlite
13710 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
13720 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
13730 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
13740 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
13750 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
13760 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
13770 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
13780 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
13790 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
137a0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
137b0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
137c0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
137d0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
137e0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
137f0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
13800 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
13810 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
13820 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
13830 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
13840 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
13850 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
13860 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
13870 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
13880 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
13890 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
138a0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
138b0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
138c0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
138d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
138e0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
138f0 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_free()..**.** 
13900 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
13910 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
13920 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
13930 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
13940 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13950 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
13960 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
13970 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
13980 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
13990 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
139a0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
139b0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
139c0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20   parameter.  If 
139d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
139e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
139f0 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
13a00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
13a10 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
13a20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
13a30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
13a40 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65  e3_malloc(N) whe
13a50 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
13a60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
13a70 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13a80 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63  )..** If the sec
13a90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13aa0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13ab0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
13ac0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
13ad0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
13ae0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
13af0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
13b00 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
13b10 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
13b20 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
13b30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13b40 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  )..** sqlite3_re
13b50 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
13b60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  a pointer to a m
13b70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13b80 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
13b90 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
13ba0 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69  or NULL if suffi
13bb0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
13bc0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  unavailable..** 
13bd0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
13be0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
13bf0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
13c00 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
13c10 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
13c20 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
13c30 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
13c40 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
13c50 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
13c60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13c70 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
13c80 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
13c90 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74  eed..** If sqlit
13ca0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
13cb0 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
13cc0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
13cd0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
13ce0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  reed..**.** The 
13cf0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
13d00 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
13d10 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
13d20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
13d30 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
13d40 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
13d50 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b  byte boundary. {
13d60 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  END}.**.** The d
13d70 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74  efault implement
13d80 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d  ation of the mem
13d90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13da0 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a  ubsystem uses.**
13db0 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72   the malloc(), r
13dc0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
13dd0 65 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20  e() provided by 
13de0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
13df0 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 46 31 37 33  ibrary..** {F173
13e00 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20  82} However, if 
13e10 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13e20 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
13e30 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a  QLITE_MEMORY_SIZ
13e40 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70  E=<i>NNN</i> C p
13e50 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
13e60 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c  o (where <i>NNN<
13e70 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  /i>.** is an int
13e80 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69  eger), then SQLi
13e90 74 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74  te create a stat
13ea0 69 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c  ic array of at l
13eb0 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f  east.** <i>NNN</
13ec0 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  i> bytes in size
13ed0 20 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61   and uses that a
13ee0 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20  rray for all of 
13ef0 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d  its dynamic.** m
13f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f10 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41   needs. {END}  A
13f20 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
13f30 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f   allocator optio
13f40 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64  ns.** may be add
13f50 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13f60 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  eases..**.** In 
13f70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
13f80 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
13f90 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
13fa0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
13fb0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
13fc0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
13fd0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
13fe0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
13ff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
14000 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
14010 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
14020 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
14030 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
14040 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
14050 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
14060 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
14070 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
14080 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
14090 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
140a0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
140b0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
140c0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
140d0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
140e0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
140f0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
14100 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
14110 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
14120 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
14130 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
14140 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
14150 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
14160 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
14170 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
14180 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
14190 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
141a0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
141b0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
141c0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
141d0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
141e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
141f0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  NOMEM]..**.** IN
14200 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14210 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73  {F17303}  The [s
14220 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
14230 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
14240 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
14250 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  nter to.**      
14260 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65       a newly che
14270 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f  cked-out block o
14280 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
14290 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
142a0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
142b0 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
142c0 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20  , or it returns 
142d0 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e  NULL if it is un
142e0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
142f0 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65    to fulfill the
14300 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20   request..**.** 
14310 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73  {F17304}  The [s
14320 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
14330 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
14340 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
14350 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  er if.**        
14360 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61     N is less tha
14370 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
14380 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  ro..**.** {F1730
14390 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  5}  The [sqlite3
143a0 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66  _free(P)] interf
143b0 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d  ace releases mem
143c0 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  ory previously.*
143d0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
143e0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
143f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
14400 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14410 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
14420 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69    making it avai
14430 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e  lable for reuse.
14440 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36 7d 20  .**.** {F17306} 
14450 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
14460 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20  te3_free(NULL)] 
14470 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
14480 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  -op..**.** {F173
14490 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  10}  A call to [
144a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
144b0 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c  0,N)] is equival
144c0 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
144d0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
144e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
144f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 32  ]..**.** {F17312
14500 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
14510 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
14520 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e  0)] is equivalen
14530 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20  t to a call.**  
14540 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c           to [sql
14550 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a  ite3_free(P)]..*
14560 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20 20 54  *.** {F17315}  T
14570 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
14580 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ses [sqlite3_mal
14590 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
145a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
145b0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73            and [s
145c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66  qlite3_free()] f
145d0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65  or all of its me
145e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
145f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
14600 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65   deallocation ne
14610 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  eds..**.** {F173
14620 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  18}  The [sqlite
14630 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
14640 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
14650 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74  s either a point
14660 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
14670 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68  to a block of ch
14680 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79  ecked-out memory
14690 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
146a0 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20  ytes in size.** 
146b0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69            that i
146c0 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  s 8-byte aligned
146d0 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  , or a NULL poin
146e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  ter..**.** {F173
146f0 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  21}  When [sqlit
14700 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
14710 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
14720 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
14730 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
14740 20 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69     copies the fi
14750 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63  rst K bytes of c
14760 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e  ontent from P in
14770 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20  to the newly.** 
14780 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61            alloca
14790 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65  ted block, where
147a0 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72   K is the lesser
147b0 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69   of N and the si
147c0 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ze of.**        
147d0 20 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e     the buffer P.
147e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32 7d 20  .**.** {F17322} 
147f0 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   When [sqlite3_r
14800 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74  ealloc(P,N)] ret
14810 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  urns a non-NULL 
14820 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73  pointer, it firs
14830 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  t.**           r
14840 65 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66  eleases the buff
14850 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  er P..**.** {F17
14860 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69  323}  When [sqli
14870 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
14880 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ] returns NULL, 
14890 74 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a  the buffer P is.
148a0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
148b0 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c   modified or rel
148c0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d  eased..**.** LIM
148d0 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  ITATIONS:.**.** 
148e0 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f  {U17350}  The po
148f0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
14900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
14910 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
14920 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20  _realloc()].**  
14930 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65           must be
14940 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
14950 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
14960 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
14970 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
14980 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
14990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
149a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
149b0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
149c0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ve.**           
149d0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
149e0 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31  eased..**.** {U1
149f0 37 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69  7351}  The appli
14a00 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
14a10 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
14a20 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20  y part of.**    
14a30 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f         a block o
14a40 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
14a50 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
14a60 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  sed using.**    
14a70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
14a80 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
14a90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
14aa0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
14ab0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
14ac0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
14ad0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
14ae0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
14af0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
14b00 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
14b10 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
14b20 74 69 73 74 69 63 73 20 7b 46 31 37 33 37 30 7d  tistics {F17370}
14b30 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
14b40 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
14b50 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
14b60 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
14b70 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
14b80 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
14b90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
14ba0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
14bb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
14bc0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
14bd0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
14be0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
14bf0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
14c00 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
14c10 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  TS:.**.** {F1737
14c20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
14c30 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
14c40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
14c50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
14c60 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
14c70 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
14c80 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
14c90 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
14ca0 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b   freed)..**.** {
14cb0 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c  F17373} The [sql
14cc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
14cd0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
14ce0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
14cf0 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  imum.**         
14d00 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
14d10 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
14d20 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
14d30 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20  -water mark.**  
14d40 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74          was last
14d50 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46   reset..**.** {F
14d60 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65  17374} The value
14d70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
14d80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
14d90 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
14da0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
14db0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14dc0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
14dd0 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20  verhead.**      
14de0 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c      added by SQL
14df0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
14e00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
14e10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
14e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74  .**          but
14e30 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
14e40 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
14e50 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
14e60 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20   library.**     
14e70 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68       routines th
14e80 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
14e90 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
14ea0 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 35 7d 20 54  **.** {F17375} T
14eb0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
14ec0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
14ed0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
14ee0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  t value of.**   
14ef0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
14f00 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
14f10 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
14f20 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
14f30 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
14f40 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
14f50 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
14f60 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
14f70 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
14f80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
14f90 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
14fa0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
14fb0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
14fc0 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
14fd0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
14fe0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
14ff0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
15000 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
15010 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
15020 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
15030 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
15040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
15050 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
15060 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46 31 37  r Generator {F17
15070 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  390}.**.** SQLit
15080 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
15090 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
150a0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
150b0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
150c0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
150d0 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
150e0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
150f0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
15100 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
15110 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
15120 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
15130 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
15140 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
15150 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
15160 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
15170 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
15180 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
15190 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
151a0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
151b0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
151c0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
151d0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
151e0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
151f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
15200 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
15210 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
15220 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
15230 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
15240 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
15250 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
15260 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
15270 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
15280 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
15290 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
152a0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
152b0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
152c0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
152d0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
152e0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
152f0 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
15300 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
15310 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
15320 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
15330 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
15340 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
15350 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
15360 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
15370 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
15380 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
15390 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
153a0 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {F17392} The [sq
153b0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
153c0 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
153d0 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
153e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
153f0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
15400 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
15410 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
15420 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
15430 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
15440 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
15450 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
15460 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
15470 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
15480 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12500}.**.** Th
15490 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
154a0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
154b0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
154c0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
154d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
154e0 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
154f0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
15500 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75  ument..** The au
15510 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15520 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
15530 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15540 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
15550 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
15560 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
15570 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
15580 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
15590 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
155a0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
155b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
155c0 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76  e16_v2()].  At v
155d0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
155e0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
155f0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
15600 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
15610 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
15620 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
15630 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
15640 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15650 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
15660 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
15670 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
15680 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72  wed.  The author
15690 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
156a0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
156b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
156c0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
156d0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
156e0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
156f0 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
15700 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
15710 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15720 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
15730 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
15740 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
15750 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
15760 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
15770 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
15780 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
15790 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
157a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
157b0 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
157c0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
157d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
157e0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
157f0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
15800 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
15810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
15820 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
15830 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
15840 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
15850 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
15860 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
15870 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
15880 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
15890 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
158a0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
158b0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
158c0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
158d0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
158e0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
158f0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
15900 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15910 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
15920 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
15930 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
15940 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
15950 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
15960 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
15970 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
15980 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
15990 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
159a0 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  er code is [SQLI
159b0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
159c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
159d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
159e0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
159f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15a00 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
15a10 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
15a20 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
15a30 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
15a40 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
15a50 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
15a60 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
15a70 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
15a80 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
15a90 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
15aa0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
15ab0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
15ac0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
15ad0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
15ae0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
15af0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
15b00 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20   a table..**.** 
15b10 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
15b20 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
15b30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
15b40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15b50 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
15b60 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
15b70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15b80 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68  () interface. Th
15b90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15ba0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
15bb0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
15bc0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
15bd0 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
15be0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
15bf0 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
15c00 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
15c10 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68  thorized. The th
15c20 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
15c30 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
15c40 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
15c50 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
15c60 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
15c70 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
15c80 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
15c90 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
15ca0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
15cb0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
15cc0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
15cd0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
15ce0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
15cf0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
15d00 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
15d10 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
15d20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
15d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15d40 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
15d50 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
15d60 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
15d70 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
15d80 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
15d90 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
15da0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
15db0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
15dc0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
15dd0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
15de0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
15df0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
15e00 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
15e10 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
15e20 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
15e30 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
15e40 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
15e50 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
15e60 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
15e70 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
15e80 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
15e90 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
15ea0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
15eb0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
15ec0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
15ed0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
15ee0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
15ef0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
15f00 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
15f10 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
15f20 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
15f30 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
15f40 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
15f50 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
15f60 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
15f70 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
15f80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
15f90 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
15fa0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
15fb0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
15fc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15fd0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
15fe0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
15ff0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
16000 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
16010 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
16020 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
16030 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
16040 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73  ..**.** Only a s
16050 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
16060 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
16070 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
16080 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
16090 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
160a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
160b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
160c0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
160d0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69  evious call.  Di
160e0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
160f0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
16100 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
16110 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
16120 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
16130 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
16140 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
16150 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16160 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16170 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
16180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16190 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
161a0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
161b0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
161c0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
161d0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
161e0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
161f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  step()]..**.** I
16200 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16210 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20 5b 73   {F12501} The [s
16220 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16230 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e  rizer(D,...)] in
16240 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
16250 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
16260 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16270 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61 73  ack with databas
16280 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
16290 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d 20 54  **.** {F12502} T
162a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
162b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
162c0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
162d0 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  nts are.**      
162e0 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c      being compil
162f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ed..**.** {F1250
16300 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
16310 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
16320 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
16330 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
16340 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
16350 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
16360 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
16370 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
16380 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
16390 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
163a0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
163b0 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
163c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
163d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
163e0 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
163f0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a  ll fail with an.
16400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
16410 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
16420 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70   code and an app
16430 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
16440 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  essage..**.** {F
16450 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20  12504} When the 
16460 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16470 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16480 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65  ITE_OK], the ope
16490 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ration.**       
164a0 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20     described is 
164b0 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c  processed normal
164c0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ly..**.** {F1250
164d0 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68  5} When the auth
164e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
164f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
16500 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20  DENY], the.**   
16510 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16520 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16530 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16540 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
16550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
16560 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16570 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
16580 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  il.**          w
16590 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45  ith an [SQLITE_E
165a0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
165b0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
165c0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
165d0 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61    explaining tha
165e0 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  t access is deni
165f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30  ed..**.** {F1250
16600 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  6} If the author
16610 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
16620 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
16630 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
16640 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
16650 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f  ack) is [SQLITE_
16660 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75  READ] and the au
16670 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16680 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  k returns.**    
16690 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
166a0 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20  NORE], then the 
166b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
166c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
166d0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
166e0 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76   insert a NULL v
166f0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
16700 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
16710 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
16720 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
16730 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
16740 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
16750 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16760 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68 65 20  {F12507} If the 
16770 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
16780 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
16790 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
167a0 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
167b0 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e   callback) is an
167c0 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ything other tha
167d0 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c  n [SQLITE_READ],
167e0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
167f0 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53    a return of [S
16800 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
16810 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
16820 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
16830 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  Y]..**.** {F1251
16840 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  0} The first par
16850 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16870 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
16880 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
16890 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
168a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
168b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
168c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
168d0 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65 20 73  * {F12511} The s
168e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
168f0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
16900 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
16910 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16920 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
16930 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
16940 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
16950 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
16960 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
16970 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
16980 46 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  F12512} The thir
16990 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
169a0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
169b0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
169c0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
169d0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
169e0 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a  gs that contain.
169f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69  **          addi
16a00 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
16a10 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
16a20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
16a30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 30 7d  ..**.** {F12520}
16a40 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
16a50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16a60 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64  rizer()] overrid
16a70 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
16a80 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
16a90 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
16aa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  er..**.** {F1252
16ab0 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
16ac0 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
16ad0 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
16ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
16af0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16b00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32 32 7d  ..**.** {F12522}
16b10 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
16b20 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
16b30 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16b40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
16b50 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
16b60 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
16b70 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
16b80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
16b90 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
16ba0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
16bb0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
16bc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
16bd0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
16be0 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a 2a 2a  odes {F12590}.**
16bf0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
16c00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
16c10 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
16c20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
16c30 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
16c40 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
16c50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
16c60 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
16c70 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
16c80 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
16c90 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
16ca0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
16cb0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
16cc0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16cd0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16ce0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
16cf0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
16d00 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
16d10 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
16d20 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
16d30 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
16d40 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
16d50 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
16d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
16d70 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
16d80 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
16d90 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
16da0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
16db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
16dc0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
16dd0 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d 0a 2a  Codes {F12550}.*
16de0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
16df0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16e00 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
16e10 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
16e20 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
16e30 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
16e40 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
16e50 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
16e60 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
16e70 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
16e80 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
16e90 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
16ea0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
16eb0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
16ec0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
16ed0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
16ee0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
16ef0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
16f00 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
16f10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
16f20 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
16f30 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
16f40 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
16f50 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
16f60 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
16f70 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
16f80 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
16f90 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
16fa0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
16fb0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
16fc0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
16fd0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
16fe0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
16ff0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
17000 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
17010 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17020 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35  arameter.  The 5
17030 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
17040 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
17050 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
17060 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
17070 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
17080 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
17090 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20   if applicable. 
170a0 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
170b0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
170c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
170d0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
170e0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
170f0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
17100 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
17110 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
17120 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
17130 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
17140 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
17150 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
17160 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
17170 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  de..**.** INVARI
17180 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
17190 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  551} The second 
171a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e 0a  parameter to an.
171b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
171c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
171d0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
171e0 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 61 6c   callback] is al
171f0 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ways an integer.
17200 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
17210 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
17220 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
17230 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
17240 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
17250 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
17260 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orized..**.** {F
17270 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
17280 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
17290 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  s to the.**     
172a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
172b0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
172c0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c  uthorization cal
172d0 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20  lback].**       
172e0 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d     will be param
172f0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
17300 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
17310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
17320 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68  LITE_COPY | auth
17330 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73 20  orizer code] is 
17340 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
17350 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
17360 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54 68 65  .** {F12553} The
17370 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
17380 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
17390 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
173a0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
173b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
173c0 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   is the name.** 
173d0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
173e0 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70 6c  database (exampl
173f0 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e: "main", "temp
17400 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ", etc.) if appl
17410 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  icable..**.** {F
17420 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20 70  12554} The 6th p
17430 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
17440 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
17450 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17460 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
17470 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68   callback] is th
17480 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
17490 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
174a0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
174b0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
174c0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
174d0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
174e0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
174f0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
17500 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
17510 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20  rectly from.**  
17520 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
17530 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
17540 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17550 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17560 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
17570 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
17580 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
17590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
175a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
175b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
175c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
175d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
175e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
175f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
17600 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
17610 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17620 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17630 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17640 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
17650 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
17660 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
17670 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17680 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17690 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
176a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
176b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
176c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
176d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
176e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
176f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17700 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17710 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17720 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
17730 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
17740 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
17750 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17770 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
17780 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
17790 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
177a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
177b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
177c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
177d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
177e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
177f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17800 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17810 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
17820 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
17830 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17840 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17850 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17860 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
17870 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
17880 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
17890 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
178a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
178c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
178d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
178e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
178f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17900 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
17910 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
17920 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
17930 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17940 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17950 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
17960 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
17970 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17980 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
179b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
179c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
179d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
179e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
179f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
17a00 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
17a10 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
17a20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17a30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17a40 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
17a50 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
17a60 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
17a70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17a80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17a90 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
17aa0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
17ab0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
17ac0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17ad0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
17ae0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
17af0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
17b00 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17b10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17b20 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
17b30 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
17b40 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
17b50 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
17b60 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
17b70 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
17b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17b90 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
17ba0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
17bb0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17bc0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
17bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
17be0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
17bf0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17c00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17c10 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
17c20 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
17c30 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
17c40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17c50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17c60 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
17c70 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
17c80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17c90 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
17ca0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17cb0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
17cc0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
17cd0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
17ce0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17cf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17d00 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
17d10 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
17d20 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
17d30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17d40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17d50 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
17d60 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
17d70 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
17d80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17da0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
17db0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
17dc0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
17dd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17df0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
17e00 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
17e10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
17e20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17e40 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
17e50 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
17e60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
17e70 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
17e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e90 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
17ea0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
17eb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
17ec0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
17ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
17ee0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
17ef0 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63      31   /* Func
17f00 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  tion Name   NULL
17f10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17f30 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
17f40 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
17f50 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
17f60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
17f70 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
17f80 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  ing Functions {F
17f90 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12280}.**.** The
17fa0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
17fb0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
17fc0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
17fd0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
17fe0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
17ff0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
18000 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
18010 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
18020 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18030 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
18040 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
18050 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
18060 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
18070 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
18080 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
18090 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
180a0 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
180b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
180c0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
180d0 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
180e0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
180f0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
18100 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
18110 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
18120 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
18130 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
18140 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
18150 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
18160 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
18170 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
18180 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
18190 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
181a0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
181b0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
181c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
181d0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
181e0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
181f0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
18200 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
18210 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
18220 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
18230 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
18240 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
18250 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
18260 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
18270 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
18280 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
18290 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
182a0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
182b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
182c0 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73  profile() API is
182d0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
182e0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
182f0 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62  al and.** is sub
18300 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
18310 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66  r removal in a f
18320 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a  uture release..*
18330 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72  *.** The trigger
18340 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75   reporting featu
18350 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20  re of the trace 
18360 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73  callback is cons
18370 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69  idered.** experi
18380 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75  mental and is su
18390 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
183a0 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75  or removal in fu
183b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
183c0 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * Future version
183d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
183e0 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74  t also add new t
183f0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
18400 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   invocations..**
18410 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18420 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d 20 54  **.** {F12281} T
18430 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
18440 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
18450 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  by [sqlite3_trac
18460 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  e()] is.**      
18470 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20      whenever an 
18480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
18490 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78  rst begins to ex
184a0 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20  ecute and.**    
184b0 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
184c0 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
184d0 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73  ram first begins
184e0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b   to run..**.** {
184f0 46 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c  F12282} Each cal
18500 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  l to [sqlite3_tr
18510 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73  ace()] overrides
18520 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a   the previously.
18530 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
18540 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c  stered trace cal
18550 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lback..**.** {F1
18560 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61  2283} A NULL tra
18570 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61  ce callback disa
18580 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  bles tracing..**
18590 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54 68 65  .** {F12284} The
185a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
185b0 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
185c0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
185d0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
185e0 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  he pointer which
185f0 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67   was the 3rd arg
18600 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
18610 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_trace()]..**.*
18620 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65 20 73  * {F12285} The s
18630 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
18640 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
18650 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20  back is a.**    
18660 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
18670 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
18680 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
18690 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a  e original text.
186a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
186b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
186c0 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65   as it was passe
186d0 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f  d into [sqlite3_
186e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
186f0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
18700 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20   equivalent, or 
18710 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69  an SQL comment i
18720 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65  ndicating the be
18730 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ginning.**      
18740 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72      of a trigger
18750 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a   subprogram..**.
18760 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68 65 20  ** {F12287} The 
18770 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18780 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
18790 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
187a0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
187b0 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61  *          as ea
187c0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
187d0 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a   finishes..**.**
187e0 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20 66 69   {F12288} The fi
187f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
18800 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
18810 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
18820 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
18830 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
18840 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
18850 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  file()]..**.** {
18860 46 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f  F12289} The seco
18870 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
18880 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
18890 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20  back is a.**    
188a0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
188b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
188c0 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  ng that contains
188d0 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65   the complete te
188e0 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  xt of.**        
188f0 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d    the SQL statem
18900 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72  ent as it was pr
18910 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69  ocessed by [sqli
18920 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18930 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
18940 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e   the equivalent.
18950 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30 7d 20  .**.** {F12290} 
18960 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
18970 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
18980 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
18990 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20  n estimate.**   
189a0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75         of the nu
189b0 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
189c0 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  nds of wall-cloc
189d0 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20  k time required 
189e0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  to.**          r
189f0 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  un the SQL state
18a00 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20  ment from start 
18a10 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f  to finish..*/.vo
18a20 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
18a30 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
18a40 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
18a50 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
18a60 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
18a70 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
18a80 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
18a90 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
18aa0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
18ab0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
18ac0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18ad0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
18ae0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ess Callbacks {F
18af0 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12910}.**.** Thi
18b00 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
18b10 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
18b20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
18b30 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
18b40 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
18b50 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
18b60 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
18b70 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
18b80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
18b90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
18ba0 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
18bb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
18bc0 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
18bd0 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
18be0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
18bf0 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
18c00 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
18c10 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  e query..**.** I
18c20 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
18c30 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18c40 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
18c50 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
18c60 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
18c70 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
18c80 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
18c90 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
18ca0 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
18cb0 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
18cc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
18cd0 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54 68 65  .** {F12911} The
18ce0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18cf0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
18d00 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
18d10 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
18d20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
18d30 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
18d40 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
18d50 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
18d60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18d70 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
18d80 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20 70 72   {F12912} The pr
18d90 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
18da0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
18db0 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74  for every N virt
18dc0 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ual.**          
18dd0 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c  machine opcodes,
18de0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
18df0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18e00 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  to.**          t
18e10 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  he [sqlite3_prog
18e20 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20  ress_handler()] 
18e30 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74  call that regist
18e40 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
18e50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
18e60 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
18e70 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f  n 1, sqlite3_pro
18e80 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a  gress_handler().
18e90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74 73  **          acts
18ea0 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72   as if a NULL pr
18eb0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68  ogress handler h
18ec0 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69 65  ad been specifie
18ed0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 33  d..**.** {F12913
18ee0 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
18ef0 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69  allback itself i
18f00 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
18f10 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20  the third.**    
18f20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74        argument t
18f30 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
18f40 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a  ss_handler()..**
18f50 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54 68 65  .** {F12914} The
18f60 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
18f70 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   to sqlite3_prog
18f80 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69  ress_handler() i
18f90 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
18fa0 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73  void pointer pas
18fb0 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72  sed to the progr
18fc0 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ess callback.** 
18fd0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
18fe0 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69  n each time it i
18ff0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
19000 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61 20 63   {F12915} If a c
19010 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
19020 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20  step()] results 
19030 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20  in fewer than N 
19040 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20  opcodes.**      
19050 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74      being execut
19060 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f  ed, then the pro
19070 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
19080 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e  s never invoked.
19090 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 36 7d 20  .**.** {F12916} 
190a0 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73  Every call to [s
190b0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
190c0 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20  handler()].**   
190d0 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65         overwrite
190e0 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  s any previously
190f0 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f 67   registered prog
19100 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
19110 0a 2a 2a 20 7b 46 31 32 39 31 37 7d 20 49 66 20  .** {F12917} If 
19120 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
19130 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19140 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72   NULL then no pr
19150 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  ogress.**       
19160 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e     handler is in
19170 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  voked..**.** {F1
19180 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f  2918} If the pro
19190 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
191a0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
191b0 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68  other than 0, th
191c0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
191d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61  he behavior is a
191e0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   if [sqlite3_int
191f0 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65  errupt()] had be
19200 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f  en called..*/.vo
19210 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
19220 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
19230 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
19240 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
19250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19260 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
19270 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
19280 74 69 6f 6e 20 7b 46 31 32 37 30 30 7d 0a 2a 2a  tion {F12700}.**
19290 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
192a0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
192b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
192c0 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
192d0 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
192e0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
192f0 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
19300 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
19310 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
19320 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
19330 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
19340 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
19350 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
19360 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
19370 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
19380 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61  _open16(). A [da
19390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
193a0 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
193b0 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
193c0 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
193d0 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
193e0 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
193f0 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
19400 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
19410 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
19420 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
19430 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
19440 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
19450 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
19460 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
19470 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
19480 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
19490 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66  3].** object. If
194a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
194b0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
194c0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
194d0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
194e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
194f0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
19500 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
19510 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  e] is returned. 
19520 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
19530 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
19540 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
19550 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
19560 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
19570 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
19580 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
19590 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
195a0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  r..**.** The def
195b0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
195c0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
195d0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
195e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
195f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
19600 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
19610 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
19620 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19630 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
19640 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
19650 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
19660 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
19670 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
19680 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
19690 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
196a0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
196b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
196c0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
196d0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
196e0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
196f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
19700 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
19710 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
19720 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
19730 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19740 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
19750 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
19760 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
19770 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
19780 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
19790 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
197a0 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
197b0 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
197c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
197d0 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
197e0 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 6f  rameter can be o
197f0 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ne of:.**.** <dl
19800 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  >.** <dt>[SQLITE
19810 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
19820 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19830 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
19840 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
19850 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
19860 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
19870 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
19880 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
19890 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  turned.</dd>.**.
198a0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
198b0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
198c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
198d0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
198e0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
198f0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
19900 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
19910 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
19920 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
19930 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
19940 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
19950 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
19960 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
19970 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
19980 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
19990 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
199a0 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
199b0 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
199c0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
199d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
199e0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
199f0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
19a00 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
19a10 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
19a20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
19a30 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
19a40 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
19a50 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
19a60 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
19a70 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
19a80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19a90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
19aa0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20  en16().</dd>.** 
19ab0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
19ac0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
19ad0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
19ae0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
19af0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
19b00 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
19b10 6f 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ove then the beh
19b20 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
19b30 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
19b40 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
19b50 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
19b60 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
19b70 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
19b80 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
19b90 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
19ba0 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e  ection.  This in
19bb0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
19bc0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
19bd0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
19be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
19bf0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
19c00 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
19c10 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
19c20 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
19c30 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
19c40 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
19c50 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
19c60 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
19c70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
19c80 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
19c90 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
19ca0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
19cb0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
19cc0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
19cd0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
19ce0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
19cf0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
19d00 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
19d10 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
19d20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
19d30 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
19d40 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
19d50 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
19d60 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
19d70 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
19d80 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65  d.  This private
19d90 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
19da0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
19db0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
19dc0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
19dd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
19de0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
19df0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
19e00 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
19e10 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
19e20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
19e30 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
19e40 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
19e50 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
19e60 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
19e70 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
19e80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19e90 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
19ea0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
19eb0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
19ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
19ed0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
19ee0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
19ef0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
19f00 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
19f10 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
19f20 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
19f30 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
19f40 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
19f50 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
19f60 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
19f70 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
19f80 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
19f90 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
19fa0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
19fb0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
19fc0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
19fd0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
19fe0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
19ff0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1a000 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1a010 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1a020 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a030 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1a040 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  _v2()..**.** INV
1a050 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1a060 46 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c  F12701} The [sql
1a070 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1a080 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1a090 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
1a0a0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1a0b0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1a0c0 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a   create a new.**
1a0d0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1a0e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a0f0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1a100 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1a110 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69  database file gi
1a120 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72  ven in their fir
1a130 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1a140 0a 2a 2a 20 7b 46 31 32 37 30 32 7d 20 54 68 65  .** {F12702} The
1a150 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1a160 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1a170 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20  d as UTF-8.**   
1a180 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69         for [sqli
1a190 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
1a1a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1a1b0 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31  ()] and as UTF-1
1a1c0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  6.**          in
1a1d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1a1e0 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
1a1f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
1a200 2a 0a 2a 2a 20 7b 46 31 32 37 30 33 7d 20 41 20  *.** {F12703} A 
1a210 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
1a220 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1a230 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1a240 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1a250 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1a260 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a270 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74  ] writes a point
1a280 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1a290 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1a2a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
1a2b0 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20  to *ppDb..**.** 
1a2c0 7b 46 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71  {F12704} The [sq
1a2d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1a2e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1a2f0 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
1a300 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1a310 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1a320 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1a330 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73  _OK] upon succes
1a340 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  s,.**          o
1a350 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
1a360 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
1a370 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
1a380 7b 46 31 32 37 30 36 7d 20 54 68 65 20 64 65 66  {F12706} The def
1a390 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1a3a0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1a3b0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1a3c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1a3d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1a3e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1a3f0 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20  n_v2()] will be 
1a400 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
1a410 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c  2707} The defaul
1a420 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
1a430 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
1a440 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
1a450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a460 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
1a470 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a  will be UTF-16..
1a480 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 39 7d 20 54  **.** {F12709} T
1a490 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1a4a0 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  (F,D)] interface
1a4b0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1a4c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
1a4d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1a4e0 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74  ,D,G,0)] where t
1a4f0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69  he G parameter i
1a500 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
1a510 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a520 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50  RITE]|[SQLITE_OP
1a530 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a  EN_CREATE]..**.*
1a540 2a 20 7b 46 31 32 37 31 31 7d 20 49 66 20 74 68  * {F12711} If th
1a550 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a560 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1a570 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1a580 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1a590 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1a5a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a5b0 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64  ONLY] then the d
1a5c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a5d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  d.**          fo
1a5e0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
1a5f0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 32 7d 20 49  **.** {F12712} I
1a600 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a610 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a620 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1a630 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1a640 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1a650 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1a660 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20  READWRITE] then 
1a670 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1a680 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
1a690 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77     reading and w
1a6a0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1a6b0 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69  le, or for readi
1a6c0 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a  ng only if the.*
1a6d0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20  *          file 
1a6e0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1a6f0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1a700 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a  ing system..**.*
1a710 2a 20 7b 46 31 32 37 31 33 7d 20 49 66 20 74 68  * {F12713} If th
1a720 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a730 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
1a740 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74  2(F,D,G,V)] omit
1a750 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1a760 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1a770 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1a780 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
1a790 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
1a7a0 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
1a7b0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1a7c0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1a7d0 2a 0a 2a 2a 20 7b 46 31 32 37 31 34 7d 20 49 66  *.** {F12714} If
1a7e0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1a7f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1a800 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n(v2(F,D,G,V)] c
1a810 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1a820 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1a830 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1a840 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1a850 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1a860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1a870 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74  viously exist, t
1a880 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hen an attempt i
1a890 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65  s made to create
1a8a0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1a8b0 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
1a8c0 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
1a8d0 7b 46 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {F12717} If the 
1a8e0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a8f0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
1a900 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1a910 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1a920 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1a930 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
1a940 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1a950 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a  n an private,.**
1a960 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1a970 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  ral, in-memory d
1a980 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
1a990 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1a9a0 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20  ction..**       
1a9b0 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1a9c0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1a9d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a9e0 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1a9f0 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1aa00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1aa10 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31  /todo>.**.** {F1
1aa20 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c  2719} If the fil
1aa30 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72  ename is NULL or
1aa40 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1aa50 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1aa60 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1aa70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  hemeral on-disk 
1aa80 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1aa90 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
1aaa0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1aab0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1aac0 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1aad0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1aae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1aaf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ab00 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1ab10 7b 46 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {F12721} The [da
1ab20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ab30 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  n] created by [s
1ab40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1ab50 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20  ,D,G,V)].**     
1ab60 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68       will use th
1ab70 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1ab80 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65  object identifie
1ab90 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d  d by the V param
1aba0 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  eter,.**        
1abb0 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74    or the default
1abc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1abd0 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20  bject if V is a 
1abe0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1abf0 0a 2a 2a 20 7b 46 31 32 37 32 33 7d 20 54 77 6f  .** {F12723} Two
1ac00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ac10 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61  ctions] will sha
1ac20 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68  re a common cach
1ac30 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a  e if both were.*
1ac40 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65  *          opene
1ac50 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
1ac60 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65  VFS while [share
1ac70 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61  d cache mode] wa
1ac80 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a  s enabled and.**
1ac90 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74            if bot
1aca0 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70  h filenames comp
1acb0 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20  are equal using 
1acc0 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68  memcmp() after h
1acd0 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20  aving been.**   
1ace0 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64         processed
1acf0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1ad00 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68  _vfs | xFullPath
1ad10 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20  name] method of 
1ad20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20  the VFS..*/.int 
1ad30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1ad40 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1ad50 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ad60 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ad70 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1ad80 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1ad90 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1ada0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1adb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1adc0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1add0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1ade0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1adf0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1ae00 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1ae10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1ae20 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1ae30 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1ae40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1ae50 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1ae60 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ae70 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ae80 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1ae90 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1aea0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1aeb0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1aec0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1aed0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1aee0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1aef0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1af00 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1af10 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1af20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1af30 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1af40 64 20 4d 65 73 73 61 67 65 73 20 7b 46 31 32 38  d Messages {F128
1af50 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00}.**.** The sq
1af60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1af70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1af80 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1af90 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1afa0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1afb0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1afc0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1afd0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1afe0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1aff0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1b000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b010 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1b020 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1b030 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1b040 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1b050 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1b060 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1b070 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1b080 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1b090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b0a0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1b0b0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1b0c0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1b0d0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1b0e0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1b0f0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1b100 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1b110 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1b120 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1b130 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1b140 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1b150 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1b160 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1b170 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1b180 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1b190 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1b1a0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1b1b0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1b1c0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1b1d0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1b1e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1b1f0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1b200 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1b210 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1b220 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
1b230 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1b240 20 7b 46 31 32 38 30 31 7d 20 54 68 65 20 5b 73   {F12801} The [s
1b250 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
1b260 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1b270 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1b280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65  .**          [re
1b290 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
1b2a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1b2b0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1b2c0 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1b2d0 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1b2e0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1b2f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1b300 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b310 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1b320 7b 46 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {F12803} The [sq
1b330 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1b340 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1b350 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1b360 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1b370 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1b380 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1b390 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1b3a0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1b3b0 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1b3c0 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1b3d0 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1b3e0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1b3f0 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1b400 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1b410 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1b420 0a 2a 2a 20 7b 46 31 32 38 30 37 7d 20 54 68 65  .** {F12807} The
1b430 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1b440 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
1b450 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
1b460 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1b470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1b480 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1b490 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1b4a0 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1b4b0 2a 2a 20 7b 46 31 32 38 30 38 7d 20 43 61 6c 6c  ** {F12808} Call
1b4c0 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1b4d0 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1b4e0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1b4f0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1b500 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1b510 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1b520 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1b530 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1b540 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1b550 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1b560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1b570 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1b580 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1b590 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1b5a0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1b5b0 2a 0a 2a 2a 20 7b 46 31 32 38 30 39 7d 20 49 6e  *.** {F12809} In
1b5c0 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72  terfaces that ar
1b5d0 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64  e not associated
1b5e0 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63   with a specific
1b5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1b600 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b610 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a  n] (examples:.**
1b620 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b630 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72  e3_mprintf()] or
1b640 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1b650 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1b660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20  .**          do 
1b670 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
1b680 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1b690 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1b6a0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1b6b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1b6c0 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1b6d0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1b6e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1b6f0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b700 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1b710 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1b720 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1b730 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1b740 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1b750 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b760 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1b770 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 30 30 30  t Object {F13000
1b780 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1b790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b7a0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1b7b0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1b7c0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1b7d0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1b7e0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1b7f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1b800 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1b810 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1b820 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1b830 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1b840 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1b850 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1b860 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1b870 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1b880 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1b890 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1b8a0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1b8b0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1b8c0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1b8d0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b8f0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1b900 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1b910 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1b920 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1b930 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1b940 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1b950 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1b960 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1b970 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1b980 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1b990 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1b9a0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1b9b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1b9c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1b9d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1b9e0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1b9f0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1ba00 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1ba10 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1ba20 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1ba30 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1ba40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1ba50 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1ba60 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1ba70 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1ba80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1ba90 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1baa0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1bab0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1bac0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1bad0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1bae0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1baf0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1bb00 65 20 4c 69 6d 69 74 73 20 7b 46 31 32 37 36 30  e Limits {F12760
1bb10 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
1bb20 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1bb30 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1bb40 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1bb50 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1bb60 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1bb70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1bb80 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1bb90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1bba0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1bbb0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1bbc0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1bbd0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1bbe0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1bbf0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1bc00 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1bc10 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1bc20 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1bc30 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1bc40 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1bc50 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1bc60 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1bc70 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1bc80 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68  t construct.  Th
1bc90 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
1bca0 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74  ns the old limit
1bcb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
1bcc0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
1bcd0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
1bce0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
1bcf0 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68  anged..** For th
1bd00 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1bd10 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1bd20 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1bd30 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f  hard upper.** bo
1bd40 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d  und set by a com
1bd50 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70  pile-time C prep
1bd60 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e  rocessor macro n
1bd70 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f  amed SQLITE_MAX_
1bd80 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  XYZ..** (The "_L
1bd90 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1bda0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1bdb0 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74   "_MAX_".).** At
1bdc0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1bdd0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1bde0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1bdf0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1be00 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1be10 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1be20 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
1be30 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un time limits a
1be40 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1be50 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1be60 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1be70 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1be80 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1be90 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1bea0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1beb0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1bec0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1bed0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1bee0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1bef0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1bf00 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74 68  ** webbrowser th
1bf10 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1bf20 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1bf30 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1bf40 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1bf50 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1bf60 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1bf70 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1bf80 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1bf90 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1bfa0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1bfb0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1bfc0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1bfd0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1bfe0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1bff0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1c000 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1c010 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1c020 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1c030 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1c040 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1c050 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1c060 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1c070 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1c080 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1c090 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1c0a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1c0b0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1c0c0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1c0d0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1c0e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1c0f0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1c100 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1c110 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1c120 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1c130 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1c140 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  A]..**.** This i
1c150 6e 74 65 72 66 61 63 65 20 69 73 20 63 75 72 72  nterface is curr
1c160 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
1c170 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
1c180 64 20 69 73 20 73 75 62 6a 65 63 74 0a 2a 2a 20  d is subject.** 
1c190 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
1c1a0 6f 76 61 6c 20 77 69 74 68 6f 75 74 20 70 72 69  oval without pri
1c1b0 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a 2a 0a 2a 2a  or notice..**.**
1c1c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1c1d0 2a 2a 20 7b 46 31 32 37 36 32 7d 20 41 20 73 75  ** {F12762} A su
1c1e0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1c1f0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1c200 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1c210 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  is.**          p
1c220 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20  ositive changes 
1c230 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1c240 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1c250 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1c260 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1c270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1c280 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  to the lesser of
1c290 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20   V and the hard 
1c2a0 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  upper.**        
1c2b0 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73    bound on the s
1c2c0 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73  ize of C that is
1c2d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1c2e0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  time..**.** {F12
1c2f0 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  766} A successfu
1c300 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1c310 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1c320 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61   where V is nega
1c330 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
1c340 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74   leaves the stat
1c350 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1c360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1c370 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
1c380 2a 20 7b 46 31 32 37 36 39 7d 20 41 20 73 75 63  * {F12769} A suc
1c390 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1c3a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1c3b0 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74  ,C,V)] returns t
1c3c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
1c3d0 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1c3e0 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1c3f0 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1c400 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c420 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61  tion] D as it wa
1c430 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  s prior to the c
1c440 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  all..*/.int sqli
1c450 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1c460 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1c470 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1c480 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1c490 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1c4a0 69 65 73 20 7b 46 31 32 37 39 30 7d 0a 2a 2a 20  ies {F12790}.** 
1c4b0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1c4c0 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69   category} {limi
1c4d0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1c4e0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1c4f0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1c500 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20  us aspects of a 
1c510 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c520 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61  tion].** that ca
1c530 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20  n be limited in 
1c540 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f  size by calls to
1c550 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1c560 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69  )]..** The meani
1c570 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
1c580 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73  us limits are as
1c590 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c5a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
1c5b0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1c5c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c5d0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1c5e0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1c5f0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
1c600 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
1c610 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1c620 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1c630 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1c640 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
1c650 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1c660 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1c670 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1c680 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c690 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c6a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1c6b0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1c6c0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1c6d0 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1c6e0 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  T or the maximum
1c6f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1c700 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
1c710 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
1c720 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
1c730 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
1c740 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c750 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1c760 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c770 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1c780 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1c790 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1c7a0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1c7b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1c7c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1c7d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c7e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c7f0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1c800 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1c810 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1c820 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1c830 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1c840 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c850 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1c860 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1c870 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1c880 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1c890 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1c8a0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1c8b0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c8c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
1c8d0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
1c8e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c8f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1c900 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
1c910 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c920 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1c930 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1c940 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c950 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
1c960 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e   databases.</dd>
1c970 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c980 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1c990 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
1c9a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c9b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
1c9c0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
1c9d0 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f  nt to the LIKE o
1c9e0 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74  r.** GLOB operat
1c9f0 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ors.</dd>.**.** 
1ca00 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1ca10 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1ca20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ca30 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1ca40 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20  of variables in 
1ca50 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1ca60 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20   that can.** be 
1ca70 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  bound.</dd>.** <
1ca80 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1ca90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1caa0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1cab0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
1cac0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
1cad0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
1cae0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
1caf0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1cb00 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
1cb10 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
1cb20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cb30 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
1cb40 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
1cb50 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cb60 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1cb70 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
1cb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1cb90 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
1cba0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
1cbb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1cbc0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
1cbd0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
1cbe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1cbf0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
1cc00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
1cc10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1cc20 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1cc30 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
1cc40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cc50 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1cc60 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
1cc70 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  9../*.** CAPI3RE
1cc80 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1cc90 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 46  SQL Statement {F
1cca0 31 33 30 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  13010}.** KEYWOR
1ccb0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
1ccc0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
1ccd0 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
1cce0 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
1ccf0 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
1cd00 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
1cd10 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
1cd20 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
1cd30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
1cd40 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
1cd50 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
1cd60 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
1cd70 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
1cd80 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
1cd90 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  or call to [sqli
1cda0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1cdb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1cdc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1cdd0 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  n16()]..**.** Th
1cde0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1cdf0 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
1ce00 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
1ce10 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
1ce20 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
1ce30 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1ce40 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
1ce50 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
1ce60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ce70 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
1ce80 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
1ce90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1cea0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1ceb0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
1cec0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
1ced0 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  ** If the nByte 
1cee0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1cef0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1cf00 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1cf10 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1cf20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1cf30 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f  . If nByte is no
1cf40 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1cf50 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
1cf60 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
1cf70 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
1cf80 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79   zSql.  When nBy
1cf90 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1cfa0 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1cfb0 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1cfc0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1cfd0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1cfe0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1cff0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1d000 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1d010 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1d020 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1d030 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1d040 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1d050 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1d060 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1d070 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1d080 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1d090 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1d0a0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1d0b0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1d0c0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1d0d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d0e0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1d0f0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1d100 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1d110 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1d120 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69  es..**.** *pzTai
1d130 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1d140 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
1d150 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
1d160 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  d of the.** firs
1d170 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1d180 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
1d190 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f  routines only co
1d1a0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a  mpile the first.
1d1b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
1d1c0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
1d1d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1d1e0 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e  g to what remain
1d1f0 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  s.** uncompiled.
1d200 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69  .**.** *ppStmt i
1d210 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1d220 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
1d230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1d240 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
1d250 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
1d260 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d270 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  ].  If there is 
1d280 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1d290 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1d2a0 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70  ULL.  If the inp
1d2b0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1d2c0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
1d2d0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
1d2e0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
1d2f0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1d300 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1d310 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31   NULL..** {U1301
1d320 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  8} The calling p
1d330 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1d340 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1d350 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1d360 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1d370 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1d380 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1d390 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1d3a0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a  hed with it..**.
1d3b0 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b  ** On success, [
1d3c0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1d3d0 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73  turned, otherwis
1d3e0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1d3f0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1d400 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d410 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e  _prepare_v2() an
1d420 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1d430 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61  e16_v2() interfa
1d440 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d  ces are.** recom
1d450 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e  mended for all n
1d460 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65  ew programs. The
1d470 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72   two older inter
1d480 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e  faces are retain
1d490 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61  ed.** for backwa
1d4a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1d4b0 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65  y, but their use
1d4c0 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e   is discouraged.
1d4d0 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20  .** In the "v2" 
1d4e0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1d4f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1d500 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
1d510 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
1d520 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1d530 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
1d540 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
1d550 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
1d560 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
1d570 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d580 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
1d590 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65 72   behave a differ
1d5a0 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79  ently in two way
1d5b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1d5c0 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20   <li>.** If the 
1d5d0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
1d5e0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
1d5f0 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
1d600 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
1d610 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
1d620 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
1d630 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1d650 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
1d660 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
1d670 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
1d680 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63  gain.  If the sc
1d690 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1d6a0 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1d6b0 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1d6c0 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1d6d0 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1d6e0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1d6f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1d700 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1d710 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1d720 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1d730 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1d740 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1d750 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1d760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d770 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1d780 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1d790 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1d7a0 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1d7b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1d7c0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1d7d0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1d7e0 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1d7f0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1d800 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1d810 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1d820 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20  ** <li>.** When 
1d830 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1d840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d850 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1d860 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1d870 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1d880 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1d890 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54  error codes].  T
1d8a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1d8b0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1d8c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d8d0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1d8e0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1d8f0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1d900 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f  t code.** and yo
1d910 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  u would have to 
1d920 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
1d930 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
1d940 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72  eset()] in order
1d950 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .** to find the 
1d960 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
1d970 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
1d980 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
1d990 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
1d9a0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
1d9b0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
1d9c0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
1d9d0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1d9e0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  y..** </li>.** <
1d9f0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  /ol>.**.** INVAR
1da00 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
1da10 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3011} The [sqlit
1da20 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53  e3_prepare(db,zS
1da30 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1da40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1da50 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1da60 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  zSql,...)] inter
1da70 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20  faces interpret 
1da80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1da90 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53  text in their zS
1daa0 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  ql parameter as 
1dab0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  UTF-8..**.** {F1
1dac0 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3012} The [sqlit
1dad0 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c  e3_prepare16(db,
1dae0 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a  zSql,...)] and.*
1daf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1db00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1db10 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1db20 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1db30 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1db40 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1db50 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1db60 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1db70 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1db80 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  der..**.** {F130
1db90 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65  13} If the nByte
1dba0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1dbb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dbc0 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e  (db,zSql,nByte,.
1dbd0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
1dbe0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1dbf0 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  s is less than z
1dc00 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78  ero, the SQL tex
1dc10 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
1dc20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20   read from zSql 
1dc30 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1dc40 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1dc50 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
1dc60 46 31 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e  F13014} If the n
1dc70 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1dc80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dc90 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1dca0 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1dcb0 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1dcc0 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67  iants is non-neg
1dcd0 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d  ative, then at m
1dce0 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65 73  ost nBytes bytes
1dcf0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1dd00 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61 64  SQL text is read
1dd10 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a   from zSql..**.*
1dd20 2a 20 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73  * {F13015} In [s
1dd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dd40 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a  2(db,zSql,N,P,pz
1dd50 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76  Tail)] and its v
1dd60 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20  ariants.**      
1dd70 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20      if the zSql 
1dd80 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1dd90 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ins more than on
1dda0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  e SQL statement.
1ddb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
1ddc0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1ddd0 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  LL, then *pzTail
1dde0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
1ddf0 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  t to the.**     
1de00 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65 20       first byte 
1de10 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1de20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1de30 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1de40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1de50 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a  do>What does *pz
1de60 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66  Tail point to if
1de70 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74   there is one st
1de80 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a  atement?</todo>.
1de90 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41  **.** {F13016} A
1dea0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1deb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1dec0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1ded0 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a  N,ppStmt,...)].*
1dee0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e  *          or on
1def0 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
1df00 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70  s writes into *p
1df10 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20  pStmt a pointer 
1df20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  to a new.**     
1df30 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
1df40 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70  tatement] or a p
1df50 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69  ointer to NULL i
1df60 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a  f zSql contains.
1df70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68  **          noth
1df80 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77  ing other than w
1df90 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d  hitespace or com
1dfa0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ments..**.** {F1
1dfb0 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3019} The [sqlit
1dfc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1dfd0 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69   interface and i
1dfe0 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74 75  ts variants retu
1dff0 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  rn.**          [
1e000 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e  SQLITE_OK] or an
1e010 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1e020 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66  ror code] upon f
1e030 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ailure..**.** {F
1e040 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73  13021} Before [s
1e050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1e060 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53  b,zSql,nByte,ppS
1e070 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20  tmt,pzTail)] or 
1e080 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
1e090 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73  variants returns
1e0a0 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76   an error (any v
1e0b0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1e0c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a  [SQLITE_OK]),.**
1e0d0 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20 66            they f
1e0e0 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74  irst set *ppStmt
1e0f0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
1e100 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e110 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1e120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1e130 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1e140 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e150 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1e160 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1e170 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1e180 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1e190 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1e1a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1e1b0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1e1c0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1e1d0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1e1e0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1e1f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1e200 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1e210 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1e220 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1e230 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1e240 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1e250 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1e260 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e270 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e280 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e290 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e2a0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e2b0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1e2c0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e2d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e2e0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e2f0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e300 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e310 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e320 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e330 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e340 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1e350 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e360 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e370 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e380 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e390 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1e3a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1e3b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1e3c0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1e3d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1e3e0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1e3f0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1e400 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e410 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e420 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e430 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e440 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e450 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e460 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e470 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e480 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1e490 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e4a0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e4b0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e4c0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1e4d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e4e0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1e4f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1e500 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1e510 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1e520 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1e530 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1e540 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1e550 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1e560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1e570 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1e580 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1e590 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1e5a0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1e5b0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1e5c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e5d0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1e5e0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1e5f0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1e600 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1e610 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1e620 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1e630 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46  Statement SQL {F
1e640 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  13100}.**.** Thi
1e650 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1e660 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1e670 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1e680 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1e690 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1e6a0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1e6b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e6c0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1e6d0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1e6e0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1e6f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1e700 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1e710 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e720 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
1e730 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
1e740 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
1e750 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e760 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
1e770 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1e780 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e790 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1e7a0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1e7b0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e7c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
1e7d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e7e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e7f0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
1e800 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
1e810 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
1e820 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1e830 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1e840 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
1e850 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
1e860 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1e870 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
1e880 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
1e890 7b 46 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {F13102} If the 
1e8a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e8b0 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
1e8c0 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
1e8d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e8e0 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
1e8f0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1e900 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1e910 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
1e920 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e930 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
1e940 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1e950 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
1e960 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e970 2a 20 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73  * {F13103} The s
1e980 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
1e990 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
1e9a0 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
1e9b0 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
1e9c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
1e9d0 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
1e9e0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1e9f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
1ea00 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1ea10 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1ea20 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1ea30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ea40 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1ea50 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1ea60 74 20 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45  t {F15000}.** KE
1ea70 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1ea80 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1ea90 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1eaa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1eab0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1eac0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1ead0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1eae0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1eaf0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1eb00 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1eb10 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1eb20 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1eb30 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1eb40 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1eb50 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1eb60 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1eb70 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1eb80 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1eb90 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1eba0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1ebb0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1ebc0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1ebd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1ebe0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1ebf0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1ec00 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1ec10 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1ec20 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1ec30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1ec40 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1ec50 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1ec60 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1ec70 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1ec80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ec90 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1eca0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1ecb0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1ecc0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1ecd0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1ece0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1ecf0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1ed00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1ed10 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1ed20 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1ed30 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1ed40 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1ed50 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1ed60 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1ed70 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1ed80 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1ed90 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1eda0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1edb0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1edc0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1edd0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1ede0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1edf0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ee00 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1ee10 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1ee20 68 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  h SQLITE_THREADS
1ee30 41 46 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b  AFE=0 and with [
1ee40 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1ee50 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1ee60 30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  0).** then there
1ee70 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1ee80 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1ee90 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1eea0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1eeb0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1eec0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1eed0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1eee0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1eef0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1ef00 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1ef10 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1ef20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1ef30 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1ef40 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1ef50 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1ef60 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ef70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1ef80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ef90 74 73 20 65 76 65 6e 20 69 66 20 74 68 65 79 20  ts even if they 
1efa0 61 72 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61  are single threa
1efb0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ded..**.** The s
1efc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1efd0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1efe0 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1eff0 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1f000 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f010 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1f020 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f030 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1f040 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
1f050 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1f060 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1f070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1f080 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1f090 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1f0a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1f0b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1f0c0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1f0d0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1f0e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1f0f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1f100 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1f110 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1f120 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1f130 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1f140 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1f150 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1f160 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f170 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1f180 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1f190 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1f1a0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1f1b0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1f1c0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1f1d0 20 7b 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20   {F16001}.**.** 
1f1e0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1f1f0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1f200 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1f210 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1f220 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1f230 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e   object.  A poin
1f240 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
1f250 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
1f260 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
1f270 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1f280 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1f290 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f2a0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
1f2b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1f2c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
1f2d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
1f2e0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
1f2f0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
1f300 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
1f310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
1f320 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
1f330 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1f340 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
1f350 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
1f360 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
1f370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
1f380 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
1f390 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
1f3a0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
1f3b0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
1f3c0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
1f3d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1f3e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
1f3f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
1f400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f410 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
1f420 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
1f430 65 6d 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a  ements {F13500}.
1f440 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1f450 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1f460 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1f470 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1f480 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1f490 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1f4a0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1f4b0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1f4c0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e  inding}.**.** In
1f4d0 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73   the SQL strings
1f4e0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1f4f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f500 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1f510 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
1f520 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
1f530 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e  y a parameter in
1f540 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f   one of these fo
1f550 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  rms:.**.** <ul>.
1f560 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1f570 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1f580 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1f590 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1f5a0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1f5b0 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74  * In the paramet
1f5c0 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61  er forms shown a
1f5d0 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69  bove NNN is an i
1f5e0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
1f5f0 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e  ** and VVV is an
1f600 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70   alpha-numeric p
1f610 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54  arameter name. T
1f620 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1f630 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1f640 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1f650 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f660 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1f670 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1f680 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1f690 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f6a0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1f6b0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1f6c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1f6d0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
1f6e0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1f6f0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
1f700 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1f710 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1f720 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
1f730 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
1f740 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f750 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
1f760 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1f770 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f780 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
1f790 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
1f7a0 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c  be set..** The l
1f7b0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1f7c0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1f7d0 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74  ex of 1.  When t
1f7e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
1f7f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
1f800 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
1f810 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
1f820 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
1f830 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
1f840 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
1f850 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
1f860 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20  urrence..** The 
1f870 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1f880 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1f890 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1f8a0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1f8b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f8c0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1f8d0 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69   desired.  The i
1f8e0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
1f8f0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
1f900 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
1f910 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61  N..** The NNN va
1f920 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1f930 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 63 6f  een 1 and the co
1f940 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 70 61  mpile-time.** pa
1f950 72 61 6d 65 74 65 72 20 53 51 4c 49 54 45 5f 4d  rameter SQLITE_M
1f960 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
1f970 45 52 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  ER (default valu
1f980 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54  e: 999)..**.** T
1f990 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1f9a0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
1f9b0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
1f9c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
1f9d0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
1f9e0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
1f9f0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
1fa00 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
1fa10 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
1fa20 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
1fa30 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
1fa40 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
1fa50 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1fa60 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
1fa70 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
1fa80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1fa90 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74  racters..** If t
1faa0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1fab0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
1fac0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
1fad0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
1fae0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1faf0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
1fb00 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1fb10 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  tor..**.** The f
1fb20 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1fb30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1fb40 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1fb50 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1fb60 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1fb70 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1fb80 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1fb90 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1fba0 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1fbb0 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1fbc0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1fbd0 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68  it. If the fifth
1fbe0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
1fbf0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
1fc00 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
1fc10 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
1fc20 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
1fc30 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
1fc40 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
1fc50 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
1fc60 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1fc70 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49  o be freed..** I
1fc80 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1fc90 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
1fca0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
1fcb0 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
1fcc0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
1fcd0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
1fce0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
1fcf0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
1fd00 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1fd10 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1fd20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1fd30 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1fd40 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1fd50 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1fd60 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1fd70 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1fd80 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a  ith zeroes.  A z
1fd90 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
1fda0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
1fdb0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
1fdc0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
1fdd0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
1fde0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
1fdf0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
1fe00 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
1fe10 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
1fe20 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1fe30 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
1fe40 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
1fe50 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
1fe60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1fe70 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
1fe80 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
1fe90 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74  ines..** A negat
1fea0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
1feb0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
1fec0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
1fed0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
1fee0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1fef0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75  _*() routines mu
1ff00 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74  st be called aft
1ff10 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
1ff20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e  repare_v2()] (an
1ff30 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  d its variants) 
1ff40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
1ff50 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f  t()] and.** befo
1ff60 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
1ff70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73  ()]..** Bindings
1ff80 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
1ff90 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1ffa0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
1ffb0 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61  e..** Unbound pa
1ffc0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
1ffd0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
1ffe0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1fff0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
20000 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
20010 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72  cess or an error
20020 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74   code if.** anyt
20030 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
20040 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d    [SQLITE_RANGE]
20050 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
20060 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
20070 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
20080 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45   range.  [SQLITE
20090 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
200a0 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
200b0 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54  fails..** [SQLIT
200c0 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20  E_MISUSE] might 
200d0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
200e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
200f0 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a  e called on a.**
20100 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
20110 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f   that is the wro
20120 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63  ng state or whic
20130 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65  h has already be
20140 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a  en finalized..**
20150 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69   Detection of mi
20160 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62  suse is unreliab
20170 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  le.  Application
20180 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70  s should not dep
20190 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45  end.** on SQLITE
201a0 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e  _MISUSE returns.
201b0 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20    SQLITE_MISUSE 
201c0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69  is intended to i
201d0 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c  ndicate a.** a l
201e0 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68  ogic error in th
201f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
20200 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
20210 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
20220 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20  ** panic rather 
20230 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49  than return SQLI
20240 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a  TE_MISUSE..**.**
20250 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
20260 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20270 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
20280 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20290 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
202a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
202b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
202c0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
202d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
202e0 46 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c  F13506} The [SQL
202f0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
20300 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20  ler] recognizes 
20310 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f  tokens of the fo
20320 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rms.**          
20330 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56  "?", "?NNN", "$V
20340 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64  VV", ":VVV", and
20350 20 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70   "@VVV" as SQL p
20360 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20  arameters,.**   
20370 20 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e         where NNN
20380 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65   is any sequence
20390 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
203a0 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  digits.**       
203b0 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56     and where VVV
203c0 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65   is any sequence
203d0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
203e0 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20  alphanumeric.** 
203f0 20 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74           charact
20400 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69  ers or "::" opti
20410 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20  onally followed 
20420 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74  by a string cont
20430 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
20440 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64     no spaces and
20450 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
20460 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a  n parentheses..*
20470 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d 20 54 68  *.** {F13509} Th
20480 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20  e initial value 
20490 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
204a0 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ter is NULL..**.
204b0 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54 68 65 20  ** {F13512} The 
204c0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20  index of an "?" 
204d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
204e0 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e   one larger than
204f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20500 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
20510 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
20520 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20  to the left, or 
20530 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  1 if.**         
20540 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20   the "?" is the 
20550 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
20560 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ameter..**.** {F
20570 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78  13515} The index
20580 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51   of an "?NNN" SQ
20590 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  L parameter is t
205a0 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a  he integer NNN..
205b0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38 7d 20 54  **.** {F13518} T
205c0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
205d0 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f  :VVV", "$VVV", o
205e0 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72  r "@VVV" SQL par
205f0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20  ameter is.**    
20600 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
20610 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c  s the index of l
20620 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e  eftmost occurren
20630 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ces of the same.
20640 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
20650 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f  meter, or one mo
20660 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67  re than the larg
20670 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61  est index over a
20680 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ll.**          p
20690 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
206a0 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73   left if this is
206b0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
206c0 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rence.**        
206d0 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65    of this parame
206e0 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69  ter, or 1 if thi
206f0 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  s is the leftmos
20700 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  t parameter..**.
20710 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54 68 65 20  ** {F13521} The 
20720 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  [SQL statement c
20730 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77  ompiler] fails w
20740 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52  ith an [SQLITE_R
20750 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ANGE].**        
20760 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69    error if the i
20770 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
20780 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
20790 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20   than 1.**      
207a0 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74      or greater t
207b0 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  han the compile-
207c0 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f  time SQLITE_MAX_
207d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a  VARIABLE_NUMBER.
207e0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
207f0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
20800 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b  3524} Calls to [
20810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20820 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
20830 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (S,N,V,...)].** 
20840 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61           associa
20850 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77  te the value V w
20860 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61  ith all SQL para
20870 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e  meters having an
20880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64  .**          ind
20890 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b  ex of N in the [
208a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
208b0 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nt] S..**.** {F1
208c0 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b  3527} Calls to [
208d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
208e0 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  t | sqlite3_bind
208f0 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  (S,N,...)].**   
20900 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20         override 
20910 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
20920 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
20930 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a   of S and N..**.
20940 2a 2a 20 7b 46 31 33 35 33 30 7d 20 42 69 6e 64  ** {F13530} Bind
20950 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64  ings established
20960 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   by [sqlite3_bin
20970 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
20980 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a  _bind(S,...)].**
20990 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73            persis
209a0 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74  t across calls t
209b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
209c0 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  (S)]..**.** {F13
209d0 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  533} In calls to
209e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
209f0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
20a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
20a10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
20a20 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
20a30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20a40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
20a50 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c  (S,N,V,L,D)] SQL
20a60 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69  ite binds the fi
20a70 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20  rst L.**        
20a80 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42    bytes of the B
20a90 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f  LOB or string po
20aa0 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77  inted to by V, w
20ab0 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20  hen L.**        
20ac0 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76    is non-negativ
20ad0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 36  e..**.** {F13536
20ae0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
20af0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20b00 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a  (S,N,V,L,D)] or.
20b10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20b20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
20b30 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c  (S,N,V,L,D)] SQL
20b40 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63  ite binds charac
20b50 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
20b60 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20   from V through 
20b70 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
20b80 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20  haracter when L 
20b90 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  is negative..**.
20ba0 2a 2a 20 7b 46 31 33 35 33 39 7d 20 49 6e 20 63  ** {F13539} In c
20bb0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
20bc0 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
20bd0 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
20be0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
20bf0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
20c00 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
20c10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
20c20 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
20c30 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
20c40 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
20c50 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
20c60 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
20c70 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
20c80 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a  hat the value V.
20c90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68  **          is h
20ca0 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e  eld in static un
20cb0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68  managed space th
20cc0 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e  at will not chan
20cd0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  ge.**          d
20ce0 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
20cf0 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e  me of the bindin
20d00 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 32  g..**.** {F13542
20d10 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
20d20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20d30 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
20d40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
20d50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
20d60 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
20d70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20d80 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
20d90 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
20da0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
20db0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
20dc0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41  tant [SQLITE_TRA
20dd0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75  NSIENT], the rou
20de0 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20  tine makes a.** 
20df0 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65           private
20e00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c   copy of the val
20e10 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72  ue V before it r
20e20 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  eturns..**.** {F
20e30 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20  13545} In calls 
20e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
20e50 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
20e60 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
20e70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
20e80 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
20e90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
20ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20eb0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
20ec0 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74  hen D is a point
20ed0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
20ee0 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51    a function, SQ
20ef0 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61  Lite invokes tha
20f00 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65  t function to de
20f10 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20  stroy the.**    
20f20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66        value V af
20f30 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
20f40 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61  hed using the va
20f50 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  lue V..**.** {F1
20f60 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3548} In calls t
20f70 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
20f80 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  zeroblob(S,N,V,L
20f90 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75  )] the value bou
20fa0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
20fb0 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79  s a BLOB of L by
20fc0 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c  tes, or a zero-l
20fd0 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20  ength BLOB if L 
20fe0 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  is negative..**.
20ff0 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49 6e 20 63  ** {F13551} In c
21000 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
21010 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c  _bind_value(S,N,
21020 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65  V)] the V argume
21030 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20  nt may.**       
21040 20 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b     be either a [
21050 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
21060 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
21070 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  or an.**        
21080 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73    [unprotected s
21090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
210a0 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ject..*/.int sql
210b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
210c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
210d0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
210e0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
210f0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
21100 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
21110 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21120 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
21130 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
21140 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
21150 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
21160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
21170 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
21180 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
21190 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
211a0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
211b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
211c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
211d0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
211e0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
211f0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
21200 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
21210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21220 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
21230 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
21240 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
21250 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
21260 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21270 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
21280 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
21290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
212a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
212b0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
212c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
212d0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
212e0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
212f0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
21300 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a 0a 2a 2a  s {F13600}.**.**
21310 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
21320 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
21330 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
21340 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
21350 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
21360 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21370 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
21380 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
21390 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
213a0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
213b0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
213c0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
213d0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
213e0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
213f0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21400 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
21410 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
21420 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
21430 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
21440 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
21450 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
21460 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
21470 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
21480 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
21490 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
214a0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
214b0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
214c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
214d0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
214e0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
214f0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65   of the ?NNN are
21500 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
21510 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
21520 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  he list..**.** S
21530 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
21540 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
21550 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
21560 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21570 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
21580 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
21590 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
215a0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
215b0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
215c0 2a 20 7b 46 31 33 36 30 31 7d 20 54 68 65 20 5b  * {F13601} The [
215d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
215e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d  ameter_count(S)]
215f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
21600 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
21610 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
21620 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61   of all SQL para
21630 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  meters in the.**
21640 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
21650 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21660 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74  , or 0 if S cont
21670 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
21680 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
21690 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
216a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
216b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
216c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
216d0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
216e0 6d 65 74 65 72 20 7b 46 31 33 36 32 30 7d 0a 2a  meter {F13620}.*
216f0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
21700 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
21710 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  ter to the name 
21720 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b  of the n-th.** [
21730 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
21740 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
21750 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c  atement]..** SQL
21760 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
21770 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
21780 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
21790 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
217a0 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
217b0 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
217c0 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
217d0 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
217e0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
217f0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
21800 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
21810 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
21820 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
21830 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
21840 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
21850 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20  ..** Parameters 
21860 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
21870 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
21880 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
21890 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
218a0 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65  are also referre
218b0 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f  d to as "anonymo
218c0 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
218d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
218e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
218f0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
21900 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  , not 0..**.** I
21910 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73  f the value n is
21920 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
21930 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72   if the n-th par
21940 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
21950 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
21960 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
21970 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
21980 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
21990 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
219a0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
219b0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
219c0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
219d0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
219e0 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
219f0 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
21a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21a10 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
21a20 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21a30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
21a50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21a60 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21a70 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
21a80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21a90 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21aa0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21ab0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32 31 7d 20  .**.** {F13621} 
21ac0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
21ad0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21ae0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
21af0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
21b00 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e       a UTF-8 ren
21b10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61  dering of the na
21b20 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  me of the SQL pa
21b30 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20  rameter in.**   
21b40 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
21b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21b60 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e  S having index N
21b70 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
21b80 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
21b90 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74  s no SQL paramet
21ba0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
21bb0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  or if the.**    
21bc0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
21bd0 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20  with index N is 
21be0 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  an anonymous par
21bf0 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63  ameter "?"..*/.c
21c00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21c10 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21c20 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
21c30 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
21c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
21c50 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
21c60 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
21c70 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a 2a 2a 0a  ame {F13640}.**.
21c80 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
21c90 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
21ca0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
21cb0 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
21cc0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
21cd0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
21ce0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
21cf0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
21d00 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
21d10 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21d20 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
21d30 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
21d40 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
21d50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
21d60 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
21d70 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
21d80 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
21d90 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
21da0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
21db0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
21dc0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
21dd0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
21de0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21df0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
21e00 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21e10 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
21e20 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
21e30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21e40 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
21e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21e60 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21e70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
21e80 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
21e90 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
21ea0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21eb0 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
21ec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
21ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
21ee0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
21ef0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70  ameter in the [p
21f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21f10 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  t].**          S
21f20 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63   whose name matc
21f30 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74  hes the UTF-8 st
21f40 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20  ring N, or 0 if 
21f50 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20  there is.**     
21f60 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a       no match..*
21f70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
21f80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
21f90 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
21fa0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
21fb0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
21fc0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
21fd0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
21fe0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
21ff0 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a  t {F13660}.**.**
22000 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
22010 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
22020 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
22030 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
22040 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
22050 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
22060 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
22070 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22080 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
22090 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
220a0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
220b0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
220c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
220d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 36 31 7d  :.**.** {F13661}
220e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   The [sqlite3_cl
220f0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d  ear_bindings(S)]
22100 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
22110 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20  s all SQL.**    
22120 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
22130 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20  bindings in the 
22140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22150 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e  ent] S back to N
22160 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
22170 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
22180 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
22190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
221a0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
221b0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
221c0 74 20 53 65 74 20 7b 46 31 33 37 31 30 7d 0a 2a  t Set {F13710}.*
221d0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
221e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
221f0 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
22200 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
22210 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22220 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69   statement]. Thi
22230 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
22240 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
22250 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
22260 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
22270 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
22280 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 55 50  or example an UP
22290 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  DATE)..**.** INV
222a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
222b0 46 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  F13711} The [sql
222c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
222d0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
222e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
222f0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
22300 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
22310 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
22320 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72  rated by the [pr
22330 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22340 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S,.**         
22350 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
22360 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72  not generate a r
22370 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
22380 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
22390 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
223a0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
223b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
223c0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
223d0 52 65 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37  Result Set {F137
223e0 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  20}.**.** These 
223f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22400 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
22410 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
22420 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
22430 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
22440 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
22450 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
22460 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
22470 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
22480 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
22490 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
224a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
224b0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
224c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
224d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
224e0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
224f0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
22500 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
22510 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22520 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22530 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
22540 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
22550 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
22560 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  t. The second pa
22570 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
22580 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
22590 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
225a0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
225b0 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  0..**.** The ret
225c0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
225d0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
225e0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
225f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22600 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
22610 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
22620 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
22630 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
22640 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
22650 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
22660 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
22670 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
22680 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
22690 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
226a0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
226b0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
226c0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
226d0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
226e0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
226f0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
22700 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
22710 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
22720 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
22730 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ed..**.** The na
22740 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
22750 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
22760 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
22770 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
22780 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
22790 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
227a0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
227b0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
227c0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
227d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
227e0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
227f0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
22800 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
22810 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
22820 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  next..**.** INVA
22830 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
22840 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73  13721} A success
22850 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
22860 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
22870 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
22880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
22890 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
228a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
228b0 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
228c0 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   0 is.**        
228d0 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    the leftmost c
228e0 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72  olumn) for the r
228f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
22900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22920 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  ] S as a zero-te
22930 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
22940 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
22950 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66  3723} A successf
22960 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
22970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
22980 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
22990 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
229a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
229b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
229c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
229d0 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
229e0 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
229f0 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
22a00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
22a10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
22a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22a30 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
22a40 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
22a50 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
22a60 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
22a70 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
22a80 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20 54 68 65  .** {F13724} The
22a90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22aa0 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71  _name()] and [sq
22ab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22ac0 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  e16()].**       
22ad0 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
22ae0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
22af0 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20  ter if they are 
22b00 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20  unable to.**    
22b10 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d        allocate m
22b20 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
22b30 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72  eir normal retur
22b40 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a  n strings..**.**
22b50 20 7b 46 31 33 37 32 35 7d 20 49 66 20 74 68 65   {F13725} If the
22b60 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
22b70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22b80 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  name(S,N)] or.**
22b90 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22bb0 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66  (S,N)] is out of
22bc0 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65   range, then the
22bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
22be0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
22bf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
22c00 2a 0a 2a 2a 20 7b 46 31 33 37 32 36 7d 20 54 68  *.** {F13726} Th
22c10 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
22c20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
22c30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
22c40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
22c50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22c60 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72  _name16(S,N)] ar
22c70 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
22c80 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  e next.**       
22c90 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65     call to eithe
22ca0 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74  r routine with t
22cb0 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20  he same S and N 
22cc0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20  parameters.**   
22cd0 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20         or until 
22ce0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22cf0 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
22d00 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 37 7d 20  .**.** {F13727} 
22d10 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f  When a result co
22d20 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43  lumn of a [SELEC
22d30 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e  T] statement con
22d40 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
22d50 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20    an AS clause, 
22d60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74  the name of that
22d70 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69   column is the i
22d80 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20  dentifier.**    
22d90 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67        to the rig
22da0 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79  ht of the AS key
22db0 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  word..*/.const c
22dc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
22dd0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
22de0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
22df0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22e10 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22e20 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
22e30 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
22e40 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
22e50 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37  ery Result {F137
22e60 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  40}.**.** These 
22e70 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
22e80 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
22e90 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d  rmine what colum
22ea0 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62  n of what.** tab
22eb0 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61  le in which data
22ec0 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66  base a result of
22ed0 20 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d   a SELECT statem
22ee0 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a  ent comes from..
22ef0 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
22f00 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
22f10 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
22f20 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
22f30 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
22f40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
22f50 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61  ring.  The _data
22f60 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
22f70 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
22f80 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
22f90 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
22fa0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
22fb0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
22fc0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
22fd0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
22fe0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54  olumn name..** T
22ff0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
23000 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
23010 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
23020 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
23030 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
23040 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23050 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
23060 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
23070 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
23080 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
23090 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
230a0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  g..**.** The nam
230b0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
230c0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
230d0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
230e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
230f0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
23100 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  umn..**.** The f
23110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
23120 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23130 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61  alls is a [prepa
23140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23150 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
23160 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
23170 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
23180 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
23190 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
231a0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
231b0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
231c0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
231d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e  ..**.** If the N
231e0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
231f0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
23200 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
23210 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
23220 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
23230 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
23240 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
23250 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
23260 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73  n.** NULL.  Thes
23270 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
23280 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
23290 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
232a0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
232b0 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77   occurs.  Otherw
232c0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
232d0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
232e0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
232f0 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64  se, table.** and
23300 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
23310 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
23320 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
23330 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
23340 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
23350 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
23360 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
23370 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
23380 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
23390 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
233a0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
233b0 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
233c0 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
233d0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
233e0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
233f0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
23400 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
23410 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
23420 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63 65  ETADATA preproce
23430 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
23440 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37  ned..**.** {U137
23450 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
23460 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
23470 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
23480 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23490 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
234a0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
234b0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
234c0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
234d0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
234e0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
234f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
23500 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23510 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  F13741} The [sql
23520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
23530 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
23540 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23550 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
23560 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
23570 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
23580 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
23590 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
235a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
235b0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
235c0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
235d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
235e0 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
235f0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
23600 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
23610 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
23620 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
23630 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
23640 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
23650 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
23660 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
23670 2a 0a 2a 2a 20 7b 46 31 33 37 34 32 7d 20 54 68  *.** {F13742} Th
23680 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23690 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
236a0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
236b0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
236c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
236d0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
236e0 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
236f0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
23700 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
23710 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
23720 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
23730 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
23740 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23750 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
23760 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
23770 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
23780 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
23790 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
237a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
237b0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
237c0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
237d0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
237e0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
237f0 7b 46 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {F13743} The [sq
23800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
23810 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
23820 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23830 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
23840 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
23850 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
23860 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
23870 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
23880 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
23890 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
238a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
238b0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
238c0 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
238d0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
238e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
238f0 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
23900 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
23910 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
23920 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
23930 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
23940 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
23950 7b 46 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {F13744} The [sq
23960 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
23970 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
23980 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23990 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
239a0 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
239b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
239c0 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
239d0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
239e0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
239f0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
23a00 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
23a10 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
23a20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
23a30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
23a40 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
23a50 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
23a60 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
23a70 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
23a80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
23a90 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
23aa0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
23ab0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
23ac0 2a 0a 2a 2a 20 7b 46 31 33 37 34 35 7d 20 54 68  *.** {F13745} Th
23ad0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23ae0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
23af0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
23b00 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
23b10 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
23b20 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
23b30 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
23b40 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
23b50 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
23b60 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
23b70 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
23b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23b90 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
23ba0 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
23bb0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
23bc0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
23bd0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
23be0 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
23bf0 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
23c00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23c10 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
23c20 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   name..**.** {F1
23c30 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
23c40 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
23c50 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
23c60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23c70 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
23c80 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
23c90 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
23ca0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23cb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
23cc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
23cd0 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
23ce0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
23cf0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
23d00 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
23d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23d20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
23d30 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
23d40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
23d50 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65      of S is a ge
23d60 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
23d70 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
23d80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
23d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
23da0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
23db0 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20 54  **.** {F13748} T
23dc0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  he return values
23dd0 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
23de0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
23df0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
23e00 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
23e10 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
23e20 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
23e30 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65  lid for the life
23e40 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
23e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
23e70 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
23e80 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
23e90 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
23ea0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
23eb0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
23ec0 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
23ed0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
23ee0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c   column..**.** L
23ef0 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
23f00 2a 20 7b 55 31 33 37 35 31 7d 20 49 66 20 74 77  * {U13751} If tw
23f10 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
23f20 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
23f30 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
23f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23f50 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
23f60 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
23f70 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
23f80 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73         for the s
23f90 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
23fa0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
23fb0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
23fc0 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
23fd0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
23fe0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
23ff0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
24000 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
24010 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
24020 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
24030 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
24040 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24050 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24060 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
24070 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
24080 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
24090 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
240a0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
240b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
240c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
240d0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
240e0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
240f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24100 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
24110 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
24120 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
24130 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24140 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
24150 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
24160 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
24170 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
24180 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
24190 72 79 20 52 65 73 75 6c 74 20 7b 46 31 33 37 36  ry Result {F1376
241a0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0}.**.** The fir
241b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
241c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
241d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
241e0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
241f0 61 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  a SELECT stateme
24200 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
24210 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
24220 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
24230 73 65 74 20 6f 66 20 74 68 61 74 20 53 45 4c 45  set of that SELE
24240 43 54 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  CT is a table co
24250 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
24260 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24270 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
24280 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
24290 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
242a0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
242b0 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
242c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
242d0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
242e0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
242f0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
24300 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
24310 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
24320 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
24330 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
24340 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a   encoded. {END}.
24350 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
24360 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
24370 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
24380 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
24390 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
243a0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
243b0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
243c0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
243d0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
243e0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
243f0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
24400 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
24410 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
24420 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
24430 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
24440 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
24450 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
24460 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
24470 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
24480 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
24490 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
244a0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
244b0 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
244c0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
244d0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
244e0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
244f0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
24500 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
24510 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
24520 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
24530 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
24540 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
24550 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
24560 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
24570 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
24580 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
24590 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
245a0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
245b0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
245c0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
245d0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
245e0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
245f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
24600 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 31 7d  :.**.** {F13761}
24610 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
24620 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
24630 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
24640 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a  S,N)] returns a.
24650 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72  **           zer
24660 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
24670 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
24680 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
24690 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20  d datatype.**   
246a0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74          of the t
246b0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
246c0 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20   appears as the 
246d0 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
246e0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
246f0 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65    from 0) of the
24700 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
24710 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24720 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
24730 20 7b 46 31 33 37 36 32 7d 20 20 41 20 73 75 63   {F13762}  A suc
24740 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24750 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24760 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
24770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
24780 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72  turns a zero-ter
24790 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
247a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
247b0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
247c0 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20       containing 
247d0 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
247e0 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
247f0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
24800 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
24810 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
24820 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
24830 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
24840 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
24850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
24860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24870 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  t] S..**.** {F13
24880 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65  763}  If N is le
24890 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69  ss than 0 or N i
248a0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  s greater than o
248b0 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20  r equal to.**   
248c0 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62          the numb
248d0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
248e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
248f0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20  tatement] S,.** 
24900 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
24910 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24920 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73  f S is an expres
24930 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
24940 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   rather.**      
24950 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c       than a tabl
24960 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20  e column, or if 
24970 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
24980 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
24990 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
249a0 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
249b0 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
249c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
249d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
249e0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
249f0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
24a00 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24a10 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
24a20 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
24a30 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
24a40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24a50 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
24a60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
24a70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
24a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24a90 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
24aa0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
24ab0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
24ac0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
24ad0 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a 2a 2a  ment {F13200}.**
24ae0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
24af0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24b00 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
24b10 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
24b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
24b30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
24b40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24b50 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
24b60 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
24b70 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
24b80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
24b90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24ba0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
24bb0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
24bc0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
24bd0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
24be0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
24bf0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
24c00 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
24c10 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
24c20 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
24c30 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
24c40 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
24c50 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
24c60 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
24c70 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
24c80 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
24c90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
24ca0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
24cb0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
24cc0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
24cd0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
24ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
24cf0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
24d00 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
24d10 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
24d20 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
24d30 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
24d40 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
24d50 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
24d60 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
24d70 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
24d80 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
24d90 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
24da0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
24db0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
24dc0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
24dd0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
24de0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
24df0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
24e00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
24e10 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
24e20 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  ]..** With the "
24e30 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
24e40 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
24e50 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
24e60 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
24e70 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
24e80 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
24e90 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  s well..**.** [S
24ea0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
24eb0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
24ec0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
24ed0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
24ee0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
24ef0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
24f00 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
24f10 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
24f20 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a 2a 2a 20   is a COMMIT.** 
24f30 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
24f40 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
24f50 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
24f60 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
24f70 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
24f80 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
24f90 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 43 4f  ment is not a CO
24fa0 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75 72 73 20  MMIT and occurs 
24fb0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
24fc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
24fd0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
24fe0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
24ff0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
25000 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
25010 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
25020 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
25030 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
25040 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
25050 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
25060 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
25070 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
25080 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
25090 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
250a0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
250b0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
250c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
250d0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
250e0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
250f0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
25100 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
25110 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
25120 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
25130 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
25140 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
25150 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
25160 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
25170 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
25180 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
25190 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
251a0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
251b0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
251c0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
251d0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
251e0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
251f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
25200 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
25210 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
25220 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
25230 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ata..**.** [SQLI
25240 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
25250 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
25260 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
25270 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
25280 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
25290 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
252a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
252b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
252c0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
252d0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
252e0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
252f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
25300 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
25310 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
25320 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
25330 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
25340 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
25350 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
25360 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
25370 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
25380 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
25390 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
253a0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
253b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
253c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
253d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
253e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e   statement].  In
253f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25400 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
25410 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
25420 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
25430 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
25440 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
25450 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
25460 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
25470 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
25480 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
25490 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
254a0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
254b0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
254c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
254d0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
254e0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
254f0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
25500 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
25510 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
25520 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
25530 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
25540 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
25550 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
25560 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
25570 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
25580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
25590 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
255a0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
255b0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
255c0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
255d0 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  e..**.** <b>Goof
255e0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
255f0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
25600 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
25610 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
25620 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
25630 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
25640 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
25650 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
25660 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
25670 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
25680 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
25690 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
256a0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
256b0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
256c0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
256d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
256e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
256f0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
25700 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
25710 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
25720 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
25730 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
25740 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
25750 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
25760 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
25770 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
25780 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
25790 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
257a0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
257b0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
257c0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
257d0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
257e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
257f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25800 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
25810 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
25820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25830 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25840 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
25850 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
25860 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
25870 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
25880 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
25890 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
258a0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
258b0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
258c0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
258d0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
258e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
258f0 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66  .** {F13202}  If
25900 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25910 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72  tatement] S is r
25920 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20  eady to be run, 
25930 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
25940 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
25950 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61  S)] advances tha
25960 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
25970 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20  ment until.**   
25980 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69          completi
25990 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69  on or until it i
259a0 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
259b0 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
259c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
259d0 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72    result set, or
259e0 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74   until an [sqlit
259f0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
25a00 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20  nterrupt].**    
25a10 20 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d         or a run-
25a20 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72  time error occur
25a30 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 34  s..**.** {F15304
25a40 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74  }  When a call t
25a50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
25a60 53 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b  S)] causes the [
25a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25a80 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
25a90 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d   S to run to com
25aa0 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e  pletion, the fun
25ab0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
25ac0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a  QLITE_DONE]..**.
25ad0 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65  ** {F15306}  Whe
25ae0 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
25af0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74  ite3_step(S)] st
25b00 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69  ops because it i
25b10 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20  s ready to.**   
25b20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61          return a
25b30 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
25b40 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74  e result set, it
25b50 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
25b60 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  _ROW]..**.** {F1
25b70 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c  5308}  If a call
25b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25b90 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73  p(S)] encounters
25ba0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
25bb0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
25bc0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
25bd0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
25be0 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
25bf0 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e     it returns an
25c00 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
25c10 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20  or code that is 
25c20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20  not one of.**   
25c30 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
25c40 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  OK], [SQLITE_ROW
25c50 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  ], or [SQLITE_DO
25c60 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  NE]..**.** {F153
25c70 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69  10}  If an [sqli
25c80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
25c90 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
25ca0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a  run-time error.*
25cb0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
25cc0 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c  rs during a call
25cd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25ce0 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  p(S)].**        
25cf0 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72     for a [prepar
25d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25d10 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
25d20 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63             legac
25d30 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  y interfaces [sq
25d40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
25d50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
25d60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25d70 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  e16()], then the
25d80 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
25d90 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25da0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
25db0 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  ROR], [SQLITE_BU
25dc0 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  SY], or [SQLITE_
25dd0 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20  MISUSE]..*/.int 
25de0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
25df0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
25e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
25e10 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
25e20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  in a result set 
25e30 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F13770}.**.** R
25e40 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
25e50 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
25e60 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
25e70 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
25e80 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
25e90 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 37  TS:.**.** {F1377
25ea0 31 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c  1}  After a call
25eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
25ec0 70 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72  p(S)] that retur
25ed0 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ns [SQLITE_ROW],
25ee0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
25ef0 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
25f00 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
25f10 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
25f20 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20  e same value.** 
25f30 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
25f40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25f50 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74  _count(S)] funct
25f60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ion..**.** {F137
25f70 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69  72}  After [sqli
25f80 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
25f90 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61   returned any va
25fa0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
25fb0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
25fc0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f  ITE_ROW] or befo
25fd0 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  re [sqlite3_step
25fe0 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  (S)] has been ca
25ff0 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20  lled on the.**  
26000 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
26010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f  ed statement] fo
26020 72 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  r the first time
26030 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a   since it was.**
26040 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
26050 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
26060 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69  epared] or [sqli
26070 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65  te3_reset | rese
26080 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  t],.**          
26090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
260a0 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
260b0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
260c0 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
260d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
260e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
260f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26100 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
26110 44 61 74 61 74 79 70 65 73 20 7b 46 31 30 32 36  Datatypes {F1026
26120 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  5}.** KEYWORDS: 
26130 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
26140 2a 20 7b 46 31 30 32 36 36 7d 20 45 76 65 72 79  * {F10266} Every
26150 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
26160 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
26170 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
26180 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
26190 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
261a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
261b0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
261c0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
261d0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
261e0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
261f0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
26200 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
26210 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
26220 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
26230 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
26240 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
26250 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
26260 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
26270 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
26280 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
26290 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
262a0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
262b0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
262c0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
262d0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
262e0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
262f0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
26300 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
26310 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
26320 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
26330 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
26340 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
26350 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
26360 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
26370 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
26380 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
26390 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
263a0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
263b0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
263c0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
263d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
263e0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
263f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
26400 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
26410 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
26420 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
26430 20 51 75 65 72 79 20 7b 46 31 33 38 30 30 7d 0a   Query {F13800}.
26440 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
26450 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
26460 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
26470 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
26480 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
26490 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
264a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
264b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
264c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
264d0 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
264e0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
264f0 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
26500 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
26510 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
26520 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
26530 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
26540 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26550 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
26560 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
26570 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
26580 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
26590 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
265a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
265b0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
265c0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
265d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
265e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
265f0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
26600 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
26610 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
26620 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
26630 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
26640 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
26650 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
26660 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  index 0..**.** I
26670 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
26680 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
26690 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
266a0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
266b0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
266c0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
266d0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
266e0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
266f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26700 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
26710 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
26720 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
26730 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
26740 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
26750 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
26760 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
26770 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26780 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
26790 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
267a0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
267b0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
267c0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
267d0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
267e0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
267f0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
26800 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26810 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
26820 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
26830 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
26840 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
26850 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
26860 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26870 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
26880 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
26890 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
268a0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
268b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
268c0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
268d0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
268e0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
268f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
26900 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
26910 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
26920 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
26930 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26940 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
26950 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
26960 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
26970 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
26980 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
26990 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
269a0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
269b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
269c0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
269d0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
269e0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
269f0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
26a00 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
26a10 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
26a20 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
26a30 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
26a40 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
26a50 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
26a60 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
26a70 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
26a80 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
26a90 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
26aa0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
26ab0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
26ac0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
26ad0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
26ae0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
26af0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
26b00 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
26b10 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
26b20 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
26b30 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
26b40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
26b50 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
26b60 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
26b70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
26b80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
26b90 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
26ba0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
26bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26bc0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
26bd0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26be0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
26bf0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
26c00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
26c10 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
26c20 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
26c30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26c40 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
26c50 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
26c60 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
26c70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
26c80 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74  f bytes..** If t
26c90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
26ca0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
26cb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
26cc0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
26cd0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
26ce0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
26cf0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
26d00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
26d10 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
26d20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26d30 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
26d40 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
26d50 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
26d60 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
26d70 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
26d80 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
26d90 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c   string.  For cl
26da0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
26db0 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
26dc0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
26dd0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
26de0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
26df0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
26e00 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72  .**.** Strings r
26e10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
26e20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26e30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
26e40 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
26e50 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
26e60 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
26e70 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
26e80 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20    The return.** 
26e90 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
26ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
26eb0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
26ec0 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
26ed0 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
26ee0 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
26ef0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
26f00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26f10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26f20 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
26f30 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
26f40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
26f50 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
26f60 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
26f70 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
26f80 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
26f90 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54  d of UTF-8..** T
26fa0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
26fb0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
26fc0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
26fd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
26fe0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
26ff0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
27000 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
27010 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
27020 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
27030 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
27040 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27050 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
27060 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
27070 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
27080 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
27090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
270a0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
270b0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
270c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
270d0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
270e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
270f0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
27100 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
27110 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
27120 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
27130 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
27140 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
27150 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
27160 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
27170 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27180 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
27190 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
271a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
271b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
271c0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
271d0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
271e0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
271f0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
27200 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
27210 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
27220 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
27230 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
27240 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
27250 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
27260 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
27270 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
27280 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
27290 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
272a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
272b0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
272c0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
272d0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
272e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
272f0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
27300 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
27310 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
27320 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
27330 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
27340 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
27350 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
27360 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
27370 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
27380 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
27390 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
273a0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
273b0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
273c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
273d0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
273e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
273f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
27400 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
27410 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
27420 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
27430 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
27440 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
27450 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
27460 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
27470 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
27480 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
27490 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
274a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
274b0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
274c0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
274d0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
274e0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
274f0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
27500 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
27510 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
27520 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
27530 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
27540 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
27550 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
27560 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
27570 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
27580 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
27590 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
275a0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
275b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
275c0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
275d0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
275e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
275f0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
27600 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
27610 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
27620 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27630 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
27640 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
27650 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
27660 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
27670 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
27680 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
27690 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
276a0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
276b0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
276c0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
276d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
276e0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
276f0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
27700 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
27710 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
27720 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
27730 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
27740 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
27750 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
27760 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
27770 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
27780 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
27790 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
277a0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
277b0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
277c0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
277d0 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
277e0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
277f0 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
27800 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
27810 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
27820 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
27830 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
27840 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
27850 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
27860 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
27870 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
27880 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
27890 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
278a0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
278b0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
278c0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
278d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
278e0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
278f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27900 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
27910 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
27920 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
27930 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
27940 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
27950 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
27960 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
27970 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
27980 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
27990 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
279a0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
279b0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
279c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
279d0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
279e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
279f0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
27a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27a10 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
27a20 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
27a30 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
27a40 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
27a50 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
27a60 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
27a70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
27a80 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
27a90 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
27aa0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
27ab0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
27ac0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
27ad0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
27ae0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
27af0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
27b00 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
27b10 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
27b20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
27b30 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
27b40 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
27b50 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
27b60 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
27b70 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
27b80 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
27b90 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
27ba0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
27bb0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
27bc0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
27bd0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
27be0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
27bf0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
27c00 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
27c10 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
27c20 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
27c30 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
27c40 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
27c50 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
27c60 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
27c70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
27c80 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
27c90 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
27ca0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
27cb0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
27cc0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
27cd0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
27ce0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
27cf0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
27d00 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
27d10 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
27d20 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
27d30 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
27d40 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
27d50 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
27d60 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
27d70 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
27d80 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
27d90 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
27da0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
27db0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
27dc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27dd0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
27de0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27df0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
27e00 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
27e10 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
27e20 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
27e30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
27e40 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
27e50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27e60 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
27e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27e80 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
27e90 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
27ea0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
27eb0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
27ec0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27ed0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
27ee0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
27ef0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27f00 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
27f10 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
27f20 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
27f30 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
27f40 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
27f50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
27f60 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
27f70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
27f80 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
27f90 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
27fa0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
27fb0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
27fc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
27fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27fe0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
27ff0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
28000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28010 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
28020 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
28030 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28040 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
28050 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
28060 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
28070 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   The pointers re
28080 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
28090 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
280a0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
280b0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
280c0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
280d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
280e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
280f0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
28100 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28110 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
28120 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
28130 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
28140 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
28150 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
28160 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
28170 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
28180 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
28190 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
281a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
281b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
281c0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
281d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
281e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
281f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
28200 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
28210 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
28220 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
28230 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
28240 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
28250 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
28260 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
28270 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
28280 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
28290 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
282a0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
282b0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
282c0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
282d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
282e0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
282f0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
28300 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
28310 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
28320 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65  .** {F13803} The
28330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28340 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
28350 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28360 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
28370 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
28380 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
28390 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
283a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
283b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
283c0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
283d0 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72   BLOB and then r
283e0 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
283f0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
28400 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
28410 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
28420 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
28430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
28440 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
28450 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
28460 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
28470 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
28480 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
28490 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
284a0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
284b0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
284c0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
284d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
284e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
284f0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
28500 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
28510 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
28520 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28540 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  (S,N)]..**.** {F
28550 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
28560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28570 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
28580 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
28590 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
285a0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
285b0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
285c0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
285d0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
285e0 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
285f0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
28600 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
28610 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
28620 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
28630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28640 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
28650 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54 68 65 20  ** {F13812} The 
28660 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28670 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
28680 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
28690 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
286a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
286b0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
286c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
286d0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
286e0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
286f0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
28700 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
28710 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
28720 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
28730 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
28740 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  lue..**.** {F138
28750 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
28760 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
28770 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
28780 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
28790 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
287a0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
287b0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
287c0 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
287d0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
287e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
287f0 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
28800 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
28810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
28820 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
28830 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
28840 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nteger..**.** {F
28850 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  13818} The [sqli
28860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
28870 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28880 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28890 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
288a0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
288b0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
288c0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
288d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
288e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
288f0 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
28900 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28910 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
28920 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
28930 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
28940 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d  ..**.** {F13821}
28950 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28960 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
28970 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28980 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28990 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
289a0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
289b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
289c0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
289d0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
289e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
289f0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
28a00 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20  ated UTF-8.**   
28a10 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
28a20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28a30 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
28a40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32  ng..**.** {F1382
28a50 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
28a60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
28a70 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
28a80 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
28a90 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
28aa0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
28ab0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
28ac0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
28ad0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
28ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28af0 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
28b00 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
28b10 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
28b20 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
28b30 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
28b40 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
28b50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
28b60 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
28b70 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ring..**.** {F13
28b80 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
28b90 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
28ba0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
28bb0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
28bc0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
28bd0 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
28be0 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
28bf0 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
28c00 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
28c10 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
28c20 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
28c30 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
28c40 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
28c50 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28c60 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28c70 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
28c80 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
28c90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28ca0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ] S..**.** {F138
28cb0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
28cc0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c  _column_value(S,
28cd0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
28ce0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
28cf0 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61      pointer to a
28d00 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
28d10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28d20 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ject for the.** 
28d30 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
28d40 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28d50 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28d60 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
28d70 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
28d80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28d90 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
28da0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28db0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
28dc0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28dd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
28de0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
28df0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28e00 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
28e10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28e20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28e30 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
28e40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28e50 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
28e60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28e70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28e80 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
28e90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28ea0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28eb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
28ec0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
28ed0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
28ee0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
28ef0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
28f00 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
28f10 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28f20 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28f40 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
28f50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
28f60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
28f70 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
28f80 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
28f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
28fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
28fb0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
28fc0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
28fd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28fe0 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
28ff0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
29000 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a  ct {F13300}.**.*
29010 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
29020 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
29030 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
29040 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
29050 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
29060 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
29070 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
29080 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
29090 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
290a0 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
290b0 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
290c0 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  d. If execution 
290d0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
290e0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
290f0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
29100 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
29110 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
29120 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
29130 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
29140 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
29150 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
29160 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
29170 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29180 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
29190 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
291a0 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
291b0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
291c0 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
291d0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
291e0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
291f0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
29200 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
29210 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
29220 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63  terrupt]..** Inc
29230 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
29240 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
29250 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
29260 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
29270 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
29280 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
29290 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
292a0 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
292b0 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
292c0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
292d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
292e0 2a 20 7b 46 31 31 33 30 32 7d 20 54 68 65 20 5b  * {F11302} The [
292f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29300 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
29310 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20  estroys the.**  
29320 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
29330 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
29340 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a  nd releases all.
29350 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
29360 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f  ry and file reso
29370 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68  urces held by th
29380 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  at object..**.**
29390 20 7b 46 31 31 33 30 34 7d 20 49 66 20 74 68 65   {F11304} If the
293a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
293b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
293c0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
293d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
293e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
293f0 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72  S returned an er
29400 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
29410 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   then [sqlite3_f
29420 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75  inalize(S)] retu
29430 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72  rns that same er
29440 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ror..*/.int sqli
29450 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
29460 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29470 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29480 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
29490 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
294a0 62 6a 65 63 74 20 7b 46 31 33 33 33 30 7d 0a 2a  bject {F13330}.*
294b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
294c0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
294d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
294e0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
294f0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
29500 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
29510 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
29520 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
29530 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79  executed..** Any
29540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
29550 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
29560 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
29570 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
29580 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
29590 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
295a0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
295b0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
295c0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
295d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
295e0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
295f0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
29600 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54 68 65 20  ** {F11332} The 
29610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29620 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
29630 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
29640 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
29650 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20  *          back 
29660 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
29670 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
29680 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 34 7d 20  .**.** {F11334} 
29690 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
296a0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
296b0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
296c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
296d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
296e0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
296f0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
29700 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
29710 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
29720 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
29730 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
29740 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
29750 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20   on S,.**       
29760 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
29770 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
29780 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
29790 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36 7d 20 49  **.** {F11336} I
297a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
297b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
297c0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
297d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
297e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
297f0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
29800 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
29810 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29820 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
29830 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
29840 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
29850 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  e]..**.** {F1133
29860 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
29870 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
29880 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
29890 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
298a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e  *          of an
298b0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
298c0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
298d0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
298e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
298f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
29900 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
29910 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
29920 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
29930 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
29940 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31   Functions {F161
29950 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
29960 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
29970 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
29980 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
29990 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
299a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
299b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
299c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
299d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
299e0 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
299f0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
29a00 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
29a10 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
29a20 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
29a30 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
29a40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
29a50 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
29a60 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
29a70 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
29a80 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
29a90 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
29aa0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
29ab0 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
29ac0 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
29ad0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
29ae0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
29af0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
29b00 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
29b10 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
29b20 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
29b30 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
29b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
29b50 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
29b60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
29b70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
29b80 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
29b90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29ba0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29bb0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
29bc0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
29bd0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
29be0 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
29bf0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
29c00 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
29c10 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
29c20 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
29c30 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
29c40 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
29c50 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
29c60 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
29c70 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
29c80 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
29c90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
29ca0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
29cb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
29cc0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
29cd0 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
29ce0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
29cf0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
29d00 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
29d10 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
29d20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
29d30 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
29d40 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
29d50 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
29d60 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
29d70 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
29d80 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
29d90 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
29da0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
29db0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
29dc0 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
29dd0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
29de0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
29df0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
29e00 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
29e10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
29e20 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
29e30 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72  kes. If this par
29e40 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
29e50 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  ve, then the SQL
29e60 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
29e70 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
29e80 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
29e90 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
29ea0 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
29eb0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
29ec0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
29ed0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
29ee0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
29ef0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
29f00 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
29f10 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
29f20 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
29f30 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
29f40 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
29f50 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
29f60 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
29f70 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
29f80 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
29f90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
29fa0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
29fb0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
29fc0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
29fd0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
29fe0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
29ff0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2a000 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2a010 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2a020 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2a030 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2a040 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2a050 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2a060 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2a070 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2a080 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
2a090 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2a0a0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2a0b0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2a0c0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2a0d0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2a0e0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2a0f0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2a100 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2a110 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2a120 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2a130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2a140 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2a150 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2a160 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2a170 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2a180 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2a190 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2a1a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
2a1b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
2a1c0 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
2a1d0 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
2a1e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
2a1f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
2a200 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
2a210 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
2a220 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
2a230 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  data()]..**.** T
2a240 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68  he seventh, eigh
2a250 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72  th and ninth par
2a260 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20  ameters, xFunc, 
2a270 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2a280 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  , are.** pointer
2a290 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20  s to C-language 
2a2a0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69  functions that i
2a2b0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
2a2c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2a2d0 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61  aggregate. A sca
2a2e0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2a2f0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2a300 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2a310 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
2a320 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20  back only, NULL 
2a330 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
2a340 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2a350 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2a360 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2a370 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   An aggregate SQ
2a380 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2a390 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2a3a0 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
2a3b0 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
2a3c0 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
2a3d0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
2a3e0 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65  . To delete an e
2a3f0 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2a400 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2a410 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2a420 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
2a430 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
2a440 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65  ..**.** It is pe
2a450 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
2a460 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
2a470 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2a480 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
2a490 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
2a4a0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
2a4b0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
2a4c0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
2a4d0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
2a4e0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
2a4f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
2a500 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  .  SQLite will u
2a510 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
2a520 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c  entation most cl
2a530 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2a540 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2a550 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2a560 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
2a570 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2a580 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20 54 68 65  .** {F16103} The
2a590 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a5a0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69  _function16()] i
2a5b0 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73  nterface behaves
2a5c0 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20   exactly.**     
2a5d0 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74       like [sqlit
2a5e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a5f0 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77  on()] in every w
2a600 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ay except that i
2a610 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  t.**          in
2a620 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75  terprets the zFu
2a630 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d  nctionName argum
2a640 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d  ent as zero-term
2a650 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a  inated UTF-16.**
2a660 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65            native
2a670 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2a680 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74  ead of as zero-t
2a690 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e  erminated UTF-8.
2a6a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 36 7d 20  .**.** {F16106} 
2a6b0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
2a6c0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20  ocation of.**   
2a6d0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2a6e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a6f0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29  ion(D,X,N,E,...)
2a700 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
2a710 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  sters.**        
2a720 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61    or replaces ca
2a730 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
2a740 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2a750 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
2a760 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64  **          used
2a770 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2a780 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2a790 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61  amed X with N pa
2a7a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20  rameters.**     
2a7b0 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20       and having 
2a7c0 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  a preferred text
2a7d0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a   encoding of E..
2a7e0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 39 7d 20 41  **.** {F16109} A
2a7f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
2a800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2a810 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a820 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a  ,N,E,P,F,S,L)].*
2a830 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61  *          repla
2a840 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c  ces the P, F, S,
2a850 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72   and L values fr
2a860 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c  om any prior cal
2a870 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  ls with.**      
2a880 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20      the same D, 
2a890 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75  X, N, and E valu
2a8a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31  es..**.** {F1611
2a8b0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2a8c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a8d0 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2a8e0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a  ace fails with.*
2a8f0 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
2a900 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
2a910 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68  ITE_ERROR] if th
2a920 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e  e SQL function n
2a930 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20  ame X is.**     
2a940 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e       longer than
2a950 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75   255 bytes exclu
2a960 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
2a970 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
2a980 2a 2a 20 7b 46 31 36 31 31 38 7d 20 45 69 74 68  ** {F16118} Eith
2a990 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c  er F must be NUL
2a9a0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2a9b0 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c  e non-NULL or el
2a9c0 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20  se F.**         
2a9d0 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64   is non-NULL and
2a9e0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c   S and L are NUL
2a9f0 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  L, otherwise.** 
2aa00 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2aa10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2aa20 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2aa30 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  L)] returns [SQL
2aa40 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a  ITE_ERROR]..**.*
2aa50 2a 20 7b 46 31 36 31 32 31 7d 20 54 68 65 20 5b  * {F16121} The [
2aa60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2aa70 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20  unction(D,...)] 
2aa80 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2aa90 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2aaa0 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2aab0 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2aac0 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2aad0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aae0 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2aaf0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ab00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ab10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2ab20 0a 2a 2a 20 7b 46 31 36 31 32 34 7d 20 54 68 65  .** {F16124} The
2ab30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ab40 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ab50 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2ab60 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
2ab70 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
2ab80 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2ab90 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2aba0 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e  ter N (specifyin
2abb0 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  g the number.** 
2abc0 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75           of argu
2abd0 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2abe0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
2abf0 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c  registered) is l
2ac00 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
2ac10 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
2ac20 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a  er than 127..**.
2ac30 2a 2a 20 7b 46 31 36 31 32 37 7d 20 57 68 65 6e  ** {F16127} When
2ac40 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
2ac50 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ve, the [sqlite3
2ac60 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ac70 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2ac80 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2ac90 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2aca0 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2acb0 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2acc0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2acd0 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20     named X when 
2ace0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2acf0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53  guments to the S
2ad00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  QL function is.*
2ad10 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74  *          exact
2ad20 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ly N..**.** {F16
2ad30 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d  130} When N is -
2ad40 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  1, the [sqlite3_
2ad50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ad60 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2ad70 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2ad80 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2ad90 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2ada0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2adb0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2adc0 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61    named X with a
2add0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2ade0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  uments..**.** {F
2adf0 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2ae00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2ae10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ae20 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2ae30 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2ae40 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2ae50 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2ae60 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2ae70 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2ae80 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2ae90 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2aea0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2aeb0 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2aec0 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2aed0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2aee0 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66  n-zero N is pref
2aef0 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  erred..**.** {F1
2af00 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6136} When calls
2af10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2af20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2af30 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,N,E,...)].**   
2af40 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2af50 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2af60 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2af70 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  ame function X w
2af80 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2af90 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20  the same number 
2afa0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62  of arguments N b
2afb0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
2afc0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  t.**          en
2afd0 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20  codings E, then 
2afe0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2aff0 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68  on where E match
2b000 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
2b010 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f     database enco
2b020 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65  ding is preferre
2b030 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 39  d..**.** {F16139
2b040 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61  } For an aggrega
2b050 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2b060 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
2b070 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2b080 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b090 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53  on(D,X,N,E,P,0,S
2b0a0 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a  ,L)] the finaliz
2b0b0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  er.**          f
2b0c0 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61  unction L will a
2b0d0 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2b0e0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2b0f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2b100 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2b110 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2b120 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2b130 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20 57 68 65  .** {F16142} Whe
2b140 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2b150 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2b160 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2b170 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2b180 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2b190 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2b1a0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2b1b0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2b1c0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2b1d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b1e0 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2b1f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b200 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2b210 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2b220 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2b230 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2b240 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2b250 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2b260 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77  arameter are alw
2b270 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ays [protected s
2b280 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2b290 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  jects..*/.int sq
2b2a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b2b0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2b2c0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2b2d0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2b2e0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2b2f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2b300 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2b310 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2b320 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2b330 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2b340 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2b350 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2b360 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2b370 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2b380 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2b390 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2b3a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2b3b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2b3c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2b3d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2b3e0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2b3f0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2b400 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2b410 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2b420 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2b430 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2b440 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2b450 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2b460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2b470 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2b480 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2b490 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2b4a0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
2b4b0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2b4c0 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31 30 32 36  Encodings {F1026
2b4d0 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  7}.**.** These c
2b4e0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2b4f0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2b500 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2b510 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2b520 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2b530 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2b540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b550 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2b560 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b570 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2b580 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2b590 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2b5a0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2b5b0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2b5c0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2b5d0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2b5e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b5f0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2b600 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2b610 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2b620 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2b630 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2b640 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2b650 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b660 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2b670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2b680 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e  bsolete Function
2b690 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  s.**.** These fu
2b6a0 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20  nctions are all 
2b6b0 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49  now obsolete.  I
2b6c0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2b6d0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2b6e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2b6f0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2b700 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73  we continue to s
2b710 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20  upport.** these 
2b720 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65  functions.  Howe
2b730 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70  ver, new develop
2b740 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68  ment projects sh
2b750 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
2b760 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
2b770 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
2b780 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
2b790 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
2b7a0 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
2b7b0 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
2b7c0 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
2b7d0 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f  you want they do
2b7e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b7f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2b800 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b810 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2b820 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2b830 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2b840 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2b850 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2b860 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2b870 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2b880 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
2b890 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69  void);.void sqli
2b8a0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2b8b0 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  up(void);.int sq
2b8c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61  lite3_memory_ala
2b8d0 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  rm(void(*)(void*
2b8e0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69  ,sqlite3_int64,i
2b8f0 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65  nt),void*,sqlite
2b900 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  3_int64);../*.**
2b910 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2b920 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2b930 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2b940 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a 2a 0a 2a  es {F15100}.**.*
2b950 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
2b960 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b970 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
2b980 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
2b990 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
2b9a0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
2b9b0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
2b9c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
2b9d0 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
2b9e0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2b9f0 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
2ba00 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
2ba10 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
2ba20 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
2ba30 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
2ba40 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
2ba50 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ba60 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2ba70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ba80 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
2ba90 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
2baa0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2bab0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2bac0 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
2bad0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2bae0 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
2baf0 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
2bb00 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
2bb10 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
2bb20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bb30 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
2bb40 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
2bb50 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
2bb60 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
2bb70 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2bb80 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
2bb90 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
2bba0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
2bbb0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
2bbc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bbd0 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
2bbe0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
2bbf0 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
2bc00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bc10 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
2bc20 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
2bc30 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2bc40 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
2bc50 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bc60 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
2bc70 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
2bc80 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
2bc90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2bca0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
2bcb0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2bcc0 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
2bcd0 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
2bce0 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
2bcf0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
2bd00 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
2bd10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bd20 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
2bd30 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
2bd40 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
2bd50 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
2bd60 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
2bd70 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
2bd80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2bd90 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
2bda0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
2bdb0 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
2bdc0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
2bdd0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
2bde0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68  ost machine.  Th
2bdf0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
2be00 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
2be10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
2be20 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
2be30 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
2be40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2be50 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
2be60 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
2be70 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2be80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2be90 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
2bea0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
2beb0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
2bec0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
2bed0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
2bee0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
2bef0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
2bf00 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
2bf10 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
2bf20 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
2bf30 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
2bf40 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
2bf50 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
2bf60 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
2bf70 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
2bf80 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
2bf90 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
2bfa0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
2bfb0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
2bfc0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
2bfd0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
2bfe0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
2bff0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
2c000 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
2c010 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
2c020 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
2c030 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
2c040 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  n is returned..*
2c050 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
2c060 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
2c070 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
2c080 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
2c090 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
2c0a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
2c0b0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
2c0c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2c0d0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2c0e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2c0f0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
2c100 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
2c110 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
2c120 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c130 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
2c140 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2c150 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2c160 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2c170 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2c180 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
2c190 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2c1a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2c1b0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2c1c0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
2c1d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
2c1e0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
2c1f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
2c200 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  arameters..**.**
2c210 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2c220 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54 68 65 20  ** {F15103} The 
2c230 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c240 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66 61 63  lob(V)] interfac
2c250 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c260 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c270 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c280 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c290 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68  to a BLOB and th
2c2a0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  en.**          r
2c2b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c2c0 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
2c2d0 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
2c2e0 46 31 35 31 30 36 7d 20 54 68 65 20 5b 73 71 6c  F15106} The [sql
2c2f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2c300 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
2c310 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
2c320 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
2c330 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c   bytes in the BL
2c340 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  OB or string (ex
2c350 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2c360 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2c370 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2c380 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2c390 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2c3a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2c3b0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2c3c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
2c3d0 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a  e_blob(V)] or.**
2c3e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2c3f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2c400 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 39  ]..**.** {F15109
2c410 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c420 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56 29 5d  alue_bytes16(V)]
2c430 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c440 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2c450 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2c460 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2c470 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
2c480 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
2c490 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
2c4a0 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
2c4b0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2c4c0 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
2c4d0 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
2c4e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c4f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d  value_text16(V)]
2c500 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
2c510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c520 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20 5b 73  t16be(V)], or [s
2c530 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c540 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  t16le(V)]..**.**
2c550 20 7b 46 31 35 31 31 32 7d 20 54 68 65 20 5b 73   {F15112} The [s
2c560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
2c570 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ble(V)] interfac
2c580 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c590 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c5a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c5b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c5c0 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
2c5d0 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
2c5e0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2c5f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
2c600 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
2c610 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  15115} The [sqli
2c620 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 56 29  te3_value_int(V)
2c630 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c640 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c650 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c670 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36  bject V into a 6
2c680 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2c690 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
2c6a0 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65       returns the
2c6b0 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f   lower 32 bits o
2c6c0 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
2c6d0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38 7d 20 54  **.** {F15118} T
2c6e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c6f0 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e 74 65  e_int64(V)] inte
2c700 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c710 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c720 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c730 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c740 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
2c750 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2c760 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2c770 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2c780 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c790 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d 20 54 68  *.** {F15121} Th
2c7a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c7b0 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65 72 66  _text(V)] interf
2c7c0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2c7e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2c7f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2c800 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2c810 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2c820 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2c830 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2c840 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2c850 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ring..**.** {F15
2c860 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  124} The [sqlite
2c870 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
2c880 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c890 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c8a0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2c8b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c8c0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2c8d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2c8e0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2c8f0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2c900 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2c910 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
2c920 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2c930 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c940 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2c950 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54 68 65 20  ** {F15127} The 
2c960 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2c970 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e 74 65  ext16be(V)] inte
2c980 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c990 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c9a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c9b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c9c0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
2c9d0 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2c9e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2c9f0 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67 2d 65  ned UTF-16 big-e
2ca00 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
2ca10 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
2ca20 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ca30 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2ca40 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d 20 54 68  *.** {F15130} Th
2ca50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ca60 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20 69 6e  _text16le(V)] in
2ca70 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2ca80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ca90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2caa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cab0 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
2cac0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2cad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2cae0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c 69 74  igned UTF-16 lit
2caf0 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  tle-endian.**   
2cb00 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2cb10 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2cb20 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2cb30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33  ng..**.** {F1513
2cb40 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2cb50 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d 20 69  value_type(V)] i
2cb60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2cb70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65  .**          one
2cb80 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
2cb90 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ], [SQLITE_INTEG
2cba0 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
2cbb0 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  AT],.**         
2cbc0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2cbd0 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  or [SQLITE_BLOB]
2cbe0 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
2cbf0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cc00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2cc10 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a  ue] object V..**
2cc20 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20 54 68 65  .** {F15136} The
2cc30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2cc40 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56 29 5d  numeric_type(V)]
2cc50 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2cc60 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rts.**          
2cc70 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  the [protected s
2cc80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cc90 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69 74 68  ject V into eith
2cca0 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  er an integer or
2ccb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66  .**          a f
2ccc0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2ccd0 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20 64 6f  lue if it can do
2cce0 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f 73 73   so without loss
2ccf0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
2cd00 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6e 64  information, and
2cd10 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f 66 20   returns one of 
2cd20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a  [SQLITE_NULL],.*
2cd30 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2cd40 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2cd50 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2cd60 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a  LITE_TEXT], or.*
2cd70 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2cd80 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2cd90 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 0a  opriate for the.
2cda0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2cdb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2cdc0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 61  alue] object V a
2cdd0 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65 72 73  fter the convers
2cde0 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a  ion attempt..*/.
2cdf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ce00 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
2ce10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ce20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2ce30 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
2ce40 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ce50 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2ce60 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2ce70 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
2ce80 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2ce90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cea0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2ceb0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
2cec0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
2ced0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
2cee0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
2cef0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2cf00 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2cf10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cf20 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
2cf30 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2cf40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cf50 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
2cf60 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2cf70 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2cf80 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2cf90 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2cfa0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cfb0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
2cfc0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2cfd0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2cfe0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2cff0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2d000 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2d010 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2d020 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2d030 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2d040 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2d050 20 43 6f 6e 74 65 78 74 20 7b 46 31 36 32 31 30   Context {F16210
2d060 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  }.**.** The impl
2d070 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2d080 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2d090 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2d0a0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2d0b0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2d0c0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2d0d0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2d0e0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2d0f0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2d100 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2d110 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2d120 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
2d130 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
2d140 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
2d150 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
2d160 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2d170 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
2d180 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2d190 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
2d1a0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2d1b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2d1c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2d1d0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2d1e0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2d1f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2d200 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
2d210 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2d220 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
2d230 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
2d240 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
2d250 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
2d260 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2d270 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2d280 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2d290 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2d2a0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2d2b0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2d2c0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2d2d0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2d2e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d2f0 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2d300 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2d310 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2d320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2d330 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2d340 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d350 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
2d360 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2d370 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2d380 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2d390 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2d3a0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2d3b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d3c0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2d3d0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2d3e0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2d3f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2d400 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2d410 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 31 7d 20  .**.** {F16211} 
2d420 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2d430 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2d440 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d450 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2d460 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2d470 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2d480 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2d490 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2d4a0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2d4b0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2d4c0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2d4d0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
2d4e0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
2d4f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2d500 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2d510 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2d520 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
2d530 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
2d540 7b 46 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {F16213} If a me
2d550 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2d560 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2d570 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2d580 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2d590 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2d5a0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2d5b0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2d5c0 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20 53 65 63  .** {F16215} Sec
2d5d0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2d5e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2d5f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2d600 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2d610 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2d620 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2d630 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2d640 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2d650 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2d660 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2d670 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2d680 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2d690 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2d6a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2d6b0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2d6c0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37 7d 20 54  **.** {F16217} T
2d6d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2d6e0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2d6f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d700 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2d710 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2d720 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2d730 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2d740 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2d760 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d770 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2d780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d790 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2d7a0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2d7b0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2d7c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d7d0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2d7e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2d7f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2d800 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d810 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2d820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2d830 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2d840 74 69 6f 6e 73 20 7b 46 31 36 32 34 30 7d 0a 2a  tions {F16240}.*
2d850 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d860 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2d870 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d880 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2d890 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2d8a0 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2d8b0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2d8c0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2d8d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d8e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d8f0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2d900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d910 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2d920 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2d930 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2d940 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2d950 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2d960 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   {END}.**.** Thi
2d970 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
2d980 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2d990 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2d9a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
2d9b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2d9c0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
2d9d0 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  nning..**.** INV
2d9e0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2d9f0 46 31 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c  F16243} The [sql
2da00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43  ite3_user_data(C
2da10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2da20 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2da30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50  he.**          P
2da40 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2da50 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2da60 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2da70 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2da80 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2da90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2daa0 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2dab0 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2dac0 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2dad0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2dae0 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2daf0 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
2db00 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2db10 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2db20 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2db30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2db40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2db50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2db60 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2db70 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F16250}.**.** 
2db80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2db90 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2dba0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2dbb0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2dbc0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2dbd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2dbe0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2dbf0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2dc00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2dc10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2dc20 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2dc30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2dc40 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2dc50 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2dc60 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2dc70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2dc80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2dc90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2dca0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 35 33 7d  :.**.** {F16253}
2dcb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2dcc0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2dcd0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  C)] interface re
2dce0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2dcf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2dd00 44 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74  D pointer from t
2dd10 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2dd20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2dd30 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2dd40 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2dd50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2dd60 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c  ction16(D,X,N,E,
2dd70 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74  P,F,S,L)] call t
2dd80 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
2dd90 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53  registered the S
2dda0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f  QL function asso
2ddb0 63 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c  ciated with [sql
2ddc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e  ite3_context] C.
2ddd0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2dde0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2ddf0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2de00 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2de10 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2de20 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2de30 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a 2a 0a 2a  ta {F16270}.**.*
2de40 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
2de50 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
2de60 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
2de70 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2de80 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
2de90 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
2dea0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
2deb0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
2dec0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
2ded0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
2dee0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2def0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
2df00 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
2df10 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
2df20 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
2df30 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
2df40 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
2df50 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
2df60 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
2df70 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
2df80 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
2df90 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
2dfa0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
2dfb0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
2dfc0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
2dfd0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
2dfe0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
2dff0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
2e000 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2e010 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
2e020 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
2e030 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2e040 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
2e050 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
2e060 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
2e070 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
2e080 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
2e090 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e0a0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
2e0b0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
2e0c0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
2e0d0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
2e0e0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
2e0f0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
2e100 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2e110 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e120 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e130 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e140 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
2e150 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
2e160 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
2e170 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
2e180 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
2e190 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
2e1a0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
2e1b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e1c0 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20  function. If no 
2e1d0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2e1e0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2e1f0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2e200 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2e210 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2e220 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2e230 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2e240 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2e250 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2e260 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2e270 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2e280 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2e290 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2e2a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
2e2b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e2c0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e2d0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
2e2e0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
2e2f0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
2e300 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
2e310 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
2e320 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
2e330 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2e340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e350 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
2e360 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2e370 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2e380 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
2e390 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
2e3a0 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
2e3b0 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66  destroyed..** If
2e3c0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
2e3d0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
2e3e0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
2e3f0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
2e400 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
2e410 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2e420 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e430 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
2e440 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
2e450 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2e460 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2e470 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
2e480 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
2e490 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
2e4a0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
2e4b0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
2e4c0 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
2e4d0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
2e4e0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
2e4f0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
2e500 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
2e510 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
2e520 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20  time.  The only 
2e530 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
2e540 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
2e550 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
2e560 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
2e570 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
2e580 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
2e590 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
2e5a0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
2e5b0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
2e5c0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
2e5d0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
2e5e0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
2e5f0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
2e600 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
2e610 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c  * values and SQL
2e620 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a   variables..**.*
2e630 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2e640 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2e650 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2e660 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2e670 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e680 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2e690 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2e6a0 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32 7d 20 54  **.** {F16272} T
2e6b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
2e6c0 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e  auxdata(C,N)] in
2e6d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e6e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
2e6f0 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74        to metadat
2e700 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2e710 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  h the Nth parame
2e720 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
2e730 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2e740 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78      whose contex
2e750 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20  t is C, or NULL 
2e760 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  if there is no m
2e770 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2e780 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
2e790 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74  ith that paramet
2e7a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37  er..**.** {F1627
2e7b0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
2e7c0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
2e7d0 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,D)] interface 
2e7e0 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61  assigns a metada
2e7f0 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ta.**          p
2e800 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20  ointer P to the 
2e810 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
2e820 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e830 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  n with context C
2e840 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36 7d  ..**.** {F16276}
2e850 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
2e860 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
2e870 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
2e880 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  le argument.**  
2e890 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73          which is
2e8a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f   the metadata po
2e8b0 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e  inter P followin
2e8c0 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  g a call to.**  
2e8d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2e8e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
2e8f0 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69  ,P,D)] when SQLi
2e900 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
2e910 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
2e920 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a  e metadata..**.*
2e930 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69 74  * {F16277} SQLit
2e940 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
2e950 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e   metadata for an
2e960 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61   SQL function pa
2e970 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
2e980 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c      when the val
2e990 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d  ue of that param
2e9a0 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a  eter changes..**
2e9b0 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68 65  .** {F16278} Whe
2e9c0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  n [sqlite3_set_a
2e9d0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2e9e0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
2e9f0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20   destructor.**  
2ea00 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65          is calle
2ea10 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20  d for any prior 
2ea20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2ea30 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
2ea40 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  e function.**   
2ea50 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43         context C
2ea60 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e   and parameter N
2ea70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39 7d  ..**.** {F16279}
2ea80 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c   SQLite will cal
2ea90 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f  l destructors fo
2eaa0 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69  r any metadata i
2eab0 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20  t is holding.** 
2eac0 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61           in a pa
2ead0 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72  rticular [prepar
2eae0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2eaf0 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20  when either.**  
2eb00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2eb10 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73  _reset(S)] or [s
2eb20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2eb30 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
2eb40 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2eb50 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
2eb60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2eb70 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
2eb80 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
2eb90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2eba0 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
2ebb0 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
2ebc0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
2ebd0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
2ebe0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
2ebf0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
2ec00 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a 2a  r {F10280}.**.**
2ec10 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
2ec20 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
2ec30 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
2ec40 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
2ec50 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
2ec60 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
2ec70 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2ec80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
2ec90 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
2eca0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
2ecb0 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
2ecc0 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
2ecd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
2ece0 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
2ecf0 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
2ed00 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
2ed10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2ed20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
2ed30 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
2ed40 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
2ed50 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2ed60 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
2ed70 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
2ed80 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
2ed90 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
2eda0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
2edb0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2edc0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2edd0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
2ede0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
2edf0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
2ee00 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
2ee10 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
2ee20 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
2ee30 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
2ee40 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
2ee50 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
2ee60 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2ee70 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
2ee80 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
2ee90 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
2eea0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2eeb0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
2eec0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
2eed0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2eee0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
2eef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
2ef00 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
2ef10 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
2ef20 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a 0a  ion {F16400}.**.
2ef30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ef40 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
2ef50 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
2ef60 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
2ef70 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
2ef80 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
2ef90 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
2efa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2efb0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2efc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2efd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2efe0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
2eff0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2f000 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2f010 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
2f020 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
2f030 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2f040 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
2f050 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
2f060 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
2f070 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2f080 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
2f090 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
2f0a0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
2f0b0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
2f0c0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
2f0d0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2f0e0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
2f0f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2f100 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2f110 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2f120 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2f130 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f140 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
2f150 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
2f160 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
2f170 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
2f180 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
2f190 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
2f1a0 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
2f1b0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
2f1c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
2f1d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f1e0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2f1f0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2f200 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2f210 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f220 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f230 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2f240 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2f250 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2f260 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2f270 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2f280 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2f290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
2f2a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f2b0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
2f2c0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2f2d0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2f2e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f2f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f300 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
2f310 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
2f320 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
2f330 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2f340 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f350 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2f360 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f370 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2f380 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2f390 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2f3a0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2f3b0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2f3c0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2f3d0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
2f3e0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
2f3f0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
2f400 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f410 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
2f420 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f430 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
2f440 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
2f450 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
2f460 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
2f470 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
2f480 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2f490 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f4a0 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74   as UTF-8. SQLit
2f4b0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
2f4c0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
2f4d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2f4e0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
2f4f0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
2f500 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20  byte order.  If 
2f510 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f520 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
2f530 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
2f540 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f550 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
2f560 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2f570 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
2f580 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
2f590 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
2f5a0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
2f5b0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
2f5c0 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64  .** If the third
2f5d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2f5e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f5f0 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
2f600 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f610 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
2f620 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2f630 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
2f640 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
2f650 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
2f660 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2f670 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
2f680 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71  ssage..** The sq
2f690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f6a0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f6b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f6c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
2f6d0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
2f6e0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
2f6f0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
2f700 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
2f710 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
2f720 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
2f730 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
2f740 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
2f750 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
2f760 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
2f770 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  arm..** The sqli
2f780 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f790 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
2f7a0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
2f7b0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
2f7c0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
2f7d0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
2f7e0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
2f7f0 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ion.  By default
2f800 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
2f810 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
2f820 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65  ROR.  A subseque
2f830 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
2f840 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f850 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f860 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2f870 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
2f880 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
2f890 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ERROR..**.** Th
2f8a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f8b0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
2f8c0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
2f8d0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
2f8e0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
2f8f0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
2f900 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f  or BLOB is to lo
2f910 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
2f920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f930 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
2f940 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
2f950 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
2f960 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
2f970 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
2f980 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2f990 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
2f9a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f9b0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
2f9c0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2f9d0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2f9e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f9f0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2fa00 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
2fa10 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2fa20 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2fa30 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2fa40 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
2fa50 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2fa60 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2fa70 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2fa80 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2fa90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2faa0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2fab0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2fac0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2fad0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2fae0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2faf0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2fb00 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2fb10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2fb20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2fb30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2fb40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2fb50 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2fb60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fb70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2fb80 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2fb90 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
2fba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fbb0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2fbc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fbd0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2fbe0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2fbf0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2fc00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2fc10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fc20 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2fc30 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2fc40 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2fc50 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2fc60 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2fc70 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2fc80 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2fc90 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2fca0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
2fcb0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
2fcc0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
2fcd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2fce0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
2fcf0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2fd00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fd10 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2fd20 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
2fd30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2fd40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fd50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2fd60 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2fd70 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2fd80 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
2fd90 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2fda0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
2fdb0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2fdc0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
2fdd0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2fde0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2fdf0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2fe00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2fe10 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2fe20 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
2fe30 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2fe40 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
2fe50 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2fe60 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2fe70 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
2fe80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2fe90 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
2fea0 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  n result..** If 
2feb0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2fec0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fed0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2fee0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2fef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2ff00 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
2ff10 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2ff20 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
2ff30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
2ff40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
2ff50 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
2ff60 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
2ff70 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
2ff80 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
2ff90 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
2ffa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2ffb0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2ffc0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2ffd0 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ces or.** sqlite
2ffe0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2fff0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
30000 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
30010 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
30020 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
30030 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
30040 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
30050 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
30060 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
30070 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c  py the it or cal
30080 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
30090 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
300a0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
300b0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
300c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
300d0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
300e0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
300f0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
30100 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
30110 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
30120 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
30130 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
30140 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
30150 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
30160 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
30170 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
30180 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
30190 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
301a0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
301b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
301c0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
301d0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
301e0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
301f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30200 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30210 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
30220 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30230 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30240 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
30250 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30260 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
30270 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30280 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
30290 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
302a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
302b0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
302c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
302d0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
302e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
302f0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
30300 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
30310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
30320 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
30330 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
30340 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
30350 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30360 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
30370 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
30380 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
30390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
303a0 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
303b0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
303c0 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
303d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
303e0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
303f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
30400 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
30410 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
30420 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
30430 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
30440 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
30450 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
30460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30470 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30480 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
30490 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
304a0 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
304b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
304c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
304d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
304e0 2a 20 7b 46 31 36 34 30 33 7d 20 54 68 65 20 64  * {F16403} The d
304f0 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61  efault return va
30500 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c  lue from any SQL
30510 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c   function is NUL
30520 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36  L..**.** {F16406
30530 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30540 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
30550 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
30560 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30570 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30580 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30590 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74  C to be a BLOB t
305a0 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a  hat is N bytes.*
305b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65  *          in le
305c0 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f  ngth and with co
305d0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f  ntent pointed to
305e0 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   by V..**.** {F1
305f0 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6409} The [sqlit
30600 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
30610 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
30620 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30630 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30640 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30650 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c  n C to be the fl
30660 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
30670 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ue V..**.** {F16
30680 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  412} The [sqlite
30690 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43  3_result_error(C
306a0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
306b0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
306c0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
306d0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
306e0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
306f0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
30700 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
30710 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
30720 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72  ] and a UTF-8 er
30730 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
30740 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
30750 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30760 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
30770 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
30780 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
30790 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
307a0 2a 20 7b 46 31 36 34 31 35 7d 20 54 68 65 20 5b  * {F16415} The [
307b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
307c0 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
307d0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
307e0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
307f0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
30800 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30810 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
30820 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
30830 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
30840 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
30850 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
30860 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
30870 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
30880 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
30890 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
308a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
308b0 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
308c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
308d0 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
308e0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
308f0 46 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  F16418} The [sql
30900 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30910 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
30920 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30930 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
30940 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
30950 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
30960 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
30970 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
30980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
30990 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
309a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
309b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
309c0 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d 20 54 68  *.** {F16421} Th
309d0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
309e0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
309f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30a00 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
30a10 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
30a20 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30a30 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
30a40 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
30a50 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
30a60 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
30a70 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
30a80 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
30a90 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 34  e..**.** {F16424
30aa0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30ab0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
30ac0 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
30ad0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
30ae0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
30af0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
30b00 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
30b10 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
30b20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
30b30 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
30b40 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30b50 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
30b60 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d 20 54 68  *.** {F16427} Th
30b70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30b80 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
30b90 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
30ba0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
30bb0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
30bc0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
30bd0 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
30be0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
30bf0 20 7b 46 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {F16430} The [s
30c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
30c10 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
30c20 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30c30 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30c40 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30c50 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
30c60 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
30c70 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
30c80 46 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  F16433} The [sql
30c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
30ca0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
30cb0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30cc0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30cd0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30ce0 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
30cf0 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20 54 68 65  .** {F16436} The
30d00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30d10 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
30d20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30d30 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30d40 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30d50 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30d60 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  be the UTF-8 str
30d70 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
30d80 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
30d90 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
30da0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
30db0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
30dc0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
30dd0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
30de0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33  ve..**.** {F1643
30df0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
30e00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
30e10 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
30e20 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30e30 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30e40 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30e50 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
30e60 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
30e70 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
30e80 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
30e90 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30ea0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
30eb0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
30ec0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
30ed0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
30ee0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
30ef0 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d 20 54 68  *.** {F16442} Th
30f00 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30f10 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
30f20 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
30f30 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30f40 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30f50 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30f60 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
30f70 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
30f80 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
30f90 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
30fa0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
30fb0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
30fc0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
30fd0 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
30fe0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
30ff0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  ive..**.** {F164
31000 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
31010 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31020 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
31030 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31050 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31060 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
31070 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  e UTF-16 little-
31080 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
31090 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
310a0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
310b0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
310c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
310d0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
310e0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
310f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
31100 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20 54 68 65  .** {F16448} The
31110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31120 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
31130 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31140 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
31150 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
31160 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31170 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
31180 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
31190 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
311a0 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ct V..**.** {F16
311b0 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
311c0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
311d0 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
311e0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
311f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
31200 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31210 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
31220 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c  byte BLOB of all
31230 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   zeros..**.** {F
31240 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
31250 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31260 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31270 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
31280 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
31290 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
312a0 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
312b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
312c0 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
312d0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
312e0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 37  g..**.** {F16457
312f0 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
31300 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
31310 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
31320 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
31330 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
31340 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31350 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
31360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31370 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
31380 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31390 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
313a0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
313b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
313c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
313d0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
313e0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
313f0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
31400 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
31410 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
31420 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
31430 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
31440 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
31450 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
31460 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
31470 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  able..**.** {F16
31480 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
31490 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
314a0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
314b0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
314c0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
314d0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
314e0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
314f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
31500 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31510 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
31520 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31530 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
31540 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
31550 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
31560 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
31570 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
31580 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
31590 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
315a0 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
315b0 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
315c0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
315d0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
315e0 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
315f0 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
31600 2a 20 7b 46 31 36 34 36 33 7d 20 49 66 20 74 68  * {F16463} If th
31610 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
31620 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
31630 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31640 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
31650 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
31660 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
31670 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
31680 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
31690 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
316a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
316b0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
316c0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
316d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
316e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
316f0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
31700 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
31710 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
31720 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
31730 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
31740 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
31750 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  IENT] then.**   
31760 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
31770 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
31780 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
31790 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
317a0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
317b0 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
317c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
317d0 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
317e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
317f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
31800 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
31810 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
31820 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
31830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31840 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
31850 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
31860 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31870 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
31880 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
31890 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
318a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
318b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
318c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
318d0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
318e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
318f0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
31900 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
31910 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
31920 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
31930 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
31940 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
31950 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31960 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
31970 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
31980 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31990 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
319a0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
319b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
319c0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
319d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
319e0 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
319f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31a00 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
31a10 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
31a20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
31a30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31a40 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
31a50 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31a60 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
31a80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31a90 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
31aa0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31ab0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31ac0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
31ad0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31ae0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
31af0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
31b00 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
31b10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b20 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
31b30 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31b40 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
31b50 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
31b60 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31b70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31b80 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
31b90 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
31ba0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
31bb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31bc0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
31bd0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
31be0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
31bf0 20 53 65 71 75 65 6e 63 65 73 20 7b 46 31 36 36   Sequences {F166
31c00 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00}.**.** These 
31c10 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
31c20 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
31c30 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
31c40 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
31c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31c60 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
31c70 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31c80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
31c90 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
31ca0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
31cb0 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
31cc0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
31cd0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
31ce0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
31cf0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
31d00 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
31d10 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
31d20 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
31d30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31d40 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
31d50 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
31d60 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
31d70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31d80 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31d90 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
31da0 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
31db0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
31dc0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
31dd0 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
31de0 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
31df0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
31e00 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
31e10 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
31e20 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
31e30 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
31e40 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
31e50 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
31e60 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
31e70 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c  6 little-endian,
31e80 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
31e90 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
31ea0 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
31eb0 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
31ec0 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
31ed0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
31ee0 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
31ef0 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
31f00 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
31f10 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
31f20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
31f30 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
31f40 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
31f50 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
31f60 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
31f70 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
31f80 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
31f90 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
31fa0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
31fb0 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
31fc0 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
31fd0 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
31fe0 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
31ff0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
32000 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
32010 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
32020 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
32030 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
32040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
32050 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
32060 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
32070 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
32080 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
32090 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
320a0 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
320b0 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
320c0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
320d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
320e0 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
320f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32100 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
32110 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
32120 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
32130 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
32140 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
32150 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
32160 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
32170 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
32180 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
32190 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
321a0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
321b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
321c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
321d0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
321e0 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
321f0 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
32200 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
32210 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
32220 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
32230 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
32240 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
32250 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
32260 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
32270 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
32280 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
32290 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
322a0 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
322b0 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
322c0 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
322d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
322e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
322f0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
32300 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32310 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
32320 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
32330 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
32340 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
32350 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
32360 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
32370 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
32380 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
32390 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
323a0 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
323b0 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
323c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
323d0 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
323e0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
323f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32400 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
32410 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
32420 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
32430 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
32440 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
32450 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
32460 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
32470 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
32480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32490 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
324a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
324b0 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
324c0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
324d0 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d 20 41 20  *.** {F16603} A 
324e0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
324f0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
32500 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
32510 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32520 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
32530 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
32540 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
32550 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
32560 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
32570 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
32580 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
32590 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
325a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
325b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
325c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
325d0 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
325e0 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
325f0 7b 46 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {F16604} SQLite 
32600 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
32610 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
32620 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32630 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32640 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
32650 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
32660 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
32670 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
32680 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
32690 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
326a0 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
326b0 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
326c0 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
326d0 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
326e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
326f0 20 7b 46 31 36 36 30 36 7d 20 53 75 63 63 65 73   {F16606} Succes
32700 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
32710 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32720 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
32730 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
32740 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
32750 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
32760 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
32770 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
32780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
32790 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
327a0 2a 2a 20 7b 46 31 36 36 30 39 7d 20 49 66 20 74  ** {F16609} If t
327b0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
327c0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
327d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
327e0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
327f0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
32800 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
32810 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
32820 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
32830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
32840 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32850 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
32860 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  Lite..**.** {F16
32870 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
32880 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
32890 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
328a0 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
328b0 2a 20 7b 46 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {F16615} A col
328c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
328d0 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
328e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
328f0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
32900 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
32910 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
32920 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  se()]..**.** {F1
32930 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
32940 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
32950 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32960 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
32970 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
32980 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
32990 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
329a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
329b0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
329c0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
329d0 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
329e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
329f0 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  f F..**.** {F166
32a00 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
32a10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32a20 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
32a30 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
32a40 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
32a50 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
32a60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32a70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
32a80 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
32a90 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
32aa0 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
32ab0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
32ac0 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {F16624} Foll
32ad0 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
32ae0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32af0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
32b00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32b10 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
32b20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
32b30 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
32b40 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
32b50 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
32b60 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  ions on the [dat
32b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32b80 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
32b90 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
32ba0 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
32bb0 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
32bc0 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46  amed X..**.** {F
32bd0 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
32be0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32bf0 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
32c00 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
32c10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
32c20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32c30 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
32c40 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
32c50 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
32c60 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
32c70 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
32c80 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
32c90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
32cb0 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
32cc0 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68  *.** {F16630} Wh
32cd0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
32ce0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
32cf0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
32d00 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
32d10 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
32d20 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
32d30 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
32d40 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
32d50 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
32d60 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
32d70 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
32d80 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
32d90 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
32da0 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
32db0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
32dc0 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
32dd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32de0 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
32df0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
32e00 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
32e10 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
32e20 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
32e30 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
32e40 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
32e50 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
32e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32e70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
32e80 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
32e90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32ea0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
32eb0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
32ec0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
32ed0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32ee0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32ef0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
32f00 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
32f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32f20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
32f30 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
32f40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
32f50 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
32f60 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
32f70 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
32f80 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
32f90 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
32fa0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
32fb0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
32fc0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
32fd0 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a  backs {F16700}.*
32fe0 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61  *.** To avoid ha
32ff0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
33000 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
33010 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
33020 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
33030 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
33040 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
33050 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
33060 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
33070 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
33080 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
33090 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72 20  called whenever 
330a0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
330b0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
330c0 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
330d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 75 6e  **.** If the fun
330e0 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
330f0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
33100 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33110 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
33120 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
33130 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
33140 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
33150 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
33160 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
33170 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 7b 46  ded in UTF-8. {F
33180 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69 74 65  16703} If sqlite
33190 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
331a0 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
331b0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
331c0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
331d0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
331e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
331f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  ** A call to eit
33200 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
33210 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73 74 69  laces any existi
33220 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ng callback..**.
33230 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
33240 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
33250 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33260 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
33270 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
33280 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
33290 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
332a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
332b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
332c0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
332d0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
332e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
332f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
33300 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
33310 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
33320 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
33330 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
33340 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
33350 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
33360 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
33370 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
33380 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
33390 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
333a0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
333b0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
333c0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
333d0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
333e0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
333f0 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  quence..**.** Th
33400 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
33410 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
33420 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
33430 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
33440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
33450 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
33460 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33470 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
33480 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33490 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
334a0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
334b0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
334c0 7b 46 31 36 37 30 32 7d 20 41 20 73 75 63 63 65  {F16702} A succe
334d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
334e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
334f0 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a  _needed(D,P,F)].
33500 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
33510 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33520 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50 2c 46  n_needed16(D,P,F
33530 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20 20 20  )] causes.**    
33540 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62        the [datab
33550 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33560 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c  D to invoke call
33570 62 61 63 6b 20 46 20 77 69 74 68 20 66 69 72 73  back F with firs
33580 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  t.**          pa
33590 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
335a0 65 72 20 69 74 20 6e 65 65 64 73 20 61 20 63 6f  er it needs a co
335b0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
335c0 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20  n for a.**      
335d0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
335e0 71 75 65 6e 63 65 20 74 68 61 74 20 69 74 20 64  quence that it d
335f0 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f  oes not know abo
33600 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30  ut..**.** {F1670
33610 34 7d 20 45 61 63 68 20 73 75 63 63 65 73 73 66  4} Each successf
33620 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
33630 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33640 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  eded()] or.**   
33650 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33660 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
33670 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  16()] overrides 
33680 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 67  the callback reg
33690 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  istered.**      
336a0 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20      on the same 
336b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
336c0 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72 20 63  tion] by prior c
336d0 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  alls to either.*
336e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
336f0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  face..**.** {F16
33700 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66  706} The name of
33710 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 63   the requested c
33720 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33730 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 0a  n passed in the.
33740 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74 68 20  **          4th 
33750 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33760 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20   callback is in 
33770 55 54 46 2d 38 20 69 66 20 74 68 65 20 63 61 6c  UTF-8 if the cal
33780 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
33790 20 20 77 61 73 20 72 65 67 69 73 74 65 72 65 64    was registered
337a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
337b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
337c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
337d0 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d 31 36      is in UTF-16
337e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
337f0 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  er if the callba
33800 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20  ck was.**       
33810 20 20 20 72 65 67 69 73 74 65 72 65 64 20 75 73     registered us
33820 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
33830 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
33840 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
33850 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33860 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
33870 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
33880 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
33890 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
338a0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
338b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
338c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
338d0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
338e0 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
338f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
33900 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
33910 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
33920 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
33930 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
33940 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
33950 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
33960 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
33970 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
33980 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
33990 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
339a0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
339b0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
339c0 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
339d0 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
339e0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
339f0 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
33a00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33a10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33a20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
33a30 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
33a40 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
33a50 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
33a60 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
33a70 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
33a80 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
33a90 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
33aa0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
33ab0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
33ac0 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
33ad0 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
33ae0 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
33af0 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
33b00 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
33b10 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
33b20 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
33b30 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
33b40 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
33b50 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
33b60 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
33b70 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
33b80 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
33b90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
33ba0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
33bb0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
33bc0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
33bd0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
33be0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
33bf0 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
33c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
33c10 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
33c20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
33c30 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10530}.**.** 
33c40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
33c50 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
33c60 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
33c70 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
33c80 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
33c90 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
33ca0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
33cb0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
33cc0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
33cd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
33ce0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
33cf0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
33d00 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
33d10 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
33d20 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
33d30 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
33d40 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
33d50 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
33d60 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
33d70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
33d80 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
33d90 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
33da0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
33db0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
33dc0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
33dd0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
33de0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
33df0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
33e00 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
33e10 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
33e20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
33e30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
33e40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
33e50 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54  **.** {F10533} T
33e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
33e70 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
33e80 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
33e90 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
33ea0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
33eb0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
33ec0 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
33ed0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
33ee0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
33ef0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
33f00 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
33f10 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
33f20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
33f30 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54  **.** {F10536} T
33f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
33f50 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
33f60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
33f70 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
33f80 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
33f90 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
33fa0 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
33fb0 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
33fc0 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
33fd0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
33fe0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
33ff0 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
34000 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
34010 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
34020 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
34030 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
34040 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
34050 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a 2a  es {F10310}.**.*
34060 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  * If this global
34070 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
34080 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
34090 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
340a0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
340b0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
340c0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
340d0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
340e0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
340f0 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  by SQLite will b
34100 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
34110 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20   directory.  If 
34120 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
34130 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34140 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34150 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
34160 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
34170 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
34180 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
34190 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
341a0 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79  t safe to modify
341b0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f   this variable o
341c0 6e 63 65 20 61 20 5b 64 61 74 61 62 61 73 65 20  nce a [database 
341d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68  connection].** h
341e0 61 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  as been opened. 
341f0 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
34200 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
34210 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
34220 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
34230 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
34240 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
34250 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
34260 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
34270 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61  have been call a
34280 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  nd remain unchan
34290 67 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a  ged thereafter..
342a0 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
342b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
342c0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
342d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
342e0 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
342f0 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49  he Database Is I
34300 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  n Auto-Commit Mo
34310 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 20 4b  de {F12930}.** K
34320 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
34330 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
34340 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
34350 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e  _autocommit() in
34360 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34370 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a  non-zero or.** z
34380 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e  ero if the given
34390 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
343a0 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f  tion is or is no
343b0 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20  t in autocommit 
343c0 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74  mode,.** respect
343d0 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d  ively.  Autocomm
343e0 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
343f0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74   default..** Aut
34400 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
34410 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
34420 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
34430 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
34440 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65  ode is re-enable
34450 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20  d by a [COMMIT] 
34460 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a  or [ROLLBACK]..*
34470 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20  *.** If certain 
34480 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20  kinds of errors 
34490 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65  occur on a state
344a0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75  ment within a mu
344b0 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  lti-statement.**
344c0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72   transaction (er
344d0 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b  rors including [
344e0 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53  SQLITE_FULL], [S
344f0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a  QLITE_IOERR],.**
34500 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c   [SQLITE_NOMEM],
34510 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
34520 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  and [SQLITE_INTE
34530 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65  RRUPT]) then the
34540 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34550 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20  might be rolled 
34560 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
34570 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61  ly.  The only wa
34580 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74  y to.** find out
34590 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20   whether SQLite 
345a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
345b0 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
345c0 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
345d0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
345e0 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
345f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
34600 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
34610 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2931} The [sqlit
34620 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
34630 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(D)] interface 
34640 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
34650 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
34660 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74  zero if the [dat
34670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34680 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ] D is or is not
34690 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
346a0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c  *          mode,
346b0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
346c0 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75  *.** {F12932} Au
346d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
346e0 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
346f0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41  **.** {F12933} A
34700 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
34710 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
34720 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49  successful [BEGI
34730 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
34740 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74  .** {F12934} Aut
34750 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
34760 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  enabled by a suc
34770 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d  cessful [COMMIT]
34780 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a   or [ROLLBACK].*
34790 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
347a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  ment..**.** LIMI
347b0 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
347c0 55 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68  U12936} If anoth
347d0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
347e0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
347f0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
34800 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
34810 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77      connection w
34820 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
34830 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
34840 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
34850 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
34860 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
34870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
34880 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
34890 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
348a0 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
348b0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
348c0 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
348d0 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30  tatement {F13120
348e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
348f0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
34900 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34910 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34920 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
34930 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
34940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34950 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68  nt] belongs.  Th
34960 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
34970 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
34980 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
34990 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  le is the same d
349a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
349b0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
349c0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
349d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
349e0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
349f0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
34a00 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
34a10 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
34a20 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
34a30 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
34a40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
34a50 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32 33 7d  :.**.** {F13123}
34a60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
34a70 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65  _handle(S)] inte
34a80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
34a90 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
34aa0 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61      to the [data
34ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34ac0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
34ad0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34af0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69  ment] S..*/.sqli
34b00 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
34b10 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
34b20 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
34b30 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
34b40 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
34b50 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 34 30  tatement {F13140
34b60 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  }.**.** This int
34b70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
34b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
34b90 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
34ba0 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
34bb0 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
34bc0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
34bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34be0 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d  n] pDb.  If pStm
34bf0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
34c00 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
34c10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34c20 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
34c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34c40 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
34c50 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
34c60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
34c70 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72  b.  If no prepar
34c80 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
34c90 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
34ca0 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
34cb0 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
34cc0 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
34cd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
34ce0 2a 2a 20 7b 46 31 33 31 34 33 7d 20 49 66 20 44  ** {F13143} If D
34cf0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
34d00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
34d10 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f   holds one or mo
34d20 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  re.**          u
34d30 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70  nfinalized [prep
34d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
34d50 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c   and S is a NULL
34d60 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20   pointer,.**    
34d70 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
34d80 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
34d90 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
34da0 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
34db0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
34dc0 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72  to one of the pr
34dd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34de0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
34df0 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  h D..**.** {F131
34e00 34 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64  46} If D is a [d
34e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34e20 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e  on] that holds n
34e30 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a  o unfinalized.**
34e40 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
34e50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
34e60 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  and S is a NULL 
34e70 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  pointer, then.**
34e80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
34e90 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
34ea0 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
34eb0 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  l return a NULL 
34ec0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
34ed0 46 31 33 31 34 39 7d 20 49 66 20 53 20 69 73 20  F13149} If S is 
34ee0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
34ef0 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64  ement] in the [d
34f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34f10 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
34f20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74    and S is not t
34f30 68 65 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  he last prepared
34f40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c   statement in D,
34f50 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
34f60 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
34f70 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
34f80 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
34f90 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
34fa0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65         to the ne
34fb0 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
34fc0 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72  ement in D after
34fd0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 35   S..**.** {F1315
34fe0 32 7d 20 49 66 20 53 20 69 73 20 74 68 65 20 6c  2} If S is the l
34ff0 61 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ast [prepared st
35000 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a  atement] in the.
35010 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
35020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35030 5d 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71  ] D then the [sq
35040 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35050 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  D, S)].**       
35060 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
35070 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
35080 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
35090 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
350a0 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
350b0 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
350c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
350d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
350e0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
350f0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
35100 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39   Callbacks {F129
35110 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
35120 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
35130 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35140 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35150 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
35160 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
35170 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
35180 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
35190 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
351a0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
351b0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
351c0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
351d0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
351e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
351f0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
35200 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
35210 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35220 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
35230 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
35240 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
35250 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
35260 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
35270 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
35280 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
35290 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
352a0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
352b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
352c0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
352d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
352e0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
352f0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
35300 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
35310 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
35320 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
35330 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
35340 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
35350 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
35360 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
35370 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
35380 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
35390 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
353a0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
353b0 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
353c0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
353d0 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
353e0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
353f0 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
35400 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35410 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
35420 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
35430 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
35440 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
35450 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
35460 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
35470 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
35480 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
35490 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
354a0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
354b0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
354c0 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
354d0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
354e0 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
354f0 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
35500 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
35510 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
35520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
35530 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
35540 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
35550 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
35560 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
35570 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
35580 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
35590 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  sed..** The roll
355a0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
355b0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
355c0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
355d0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
355e0 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
355f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
35600 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20  ed non-zero..** 
35610 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20  <todo> Check on 
35620 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  this </todo>.**.
35630 2a 2a 20 54 68 65 73 65 20 61 72 65 20 65 78 70  ** These are exp
35640 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
35650 61 63 65 73 20 61 6e 64 20 61 72 65 20 73 75 62  aces and are sub
35660 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 2e 0a  ject to change..
35670 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
35680 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 31 7d  :.**.** {F12951}
35690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
356a0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
356b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
356c0 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
356d0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
356e0 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
356f0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
35700 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
35710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
35720 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
35730 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ts on the [datab
35740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35750 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32  D..**.** {F12952
35760 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
35770 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
35780 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
35790 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
357a0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
357b0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
357c0 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
357d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
357e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a  onnection] D,.**
357f0 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
35800 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
35810 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63  all for a partic
35820 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f  ular database co
35830 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
35840 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68 20  * {F12953} Each 
35850 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
35860 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
35870 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
35880 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
35890 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
358a0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
358b0 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49 66  *.** {F12954} If
358c0 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
358d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
358e0 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
358f0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
35900 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d      then the com
35910 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
35920 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e  k is canceled an
35930 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  d no callback.**
35940 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
35950 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e  oked when a tran
35960 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e  saction commits.
35970 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d 20  .**.** {F12955} 
35980 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61  If the commit ca
35990 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
359a0 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  on-zero then the
359b0 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20   commit is.**   
359c0 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64         converted
359d0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
359e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31 7d  ..**.** {F12961}
359f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
35a00 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
35a10 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
35a20 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
35a30 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
35a40 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
35a50 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
35a60 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
35a70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
35a80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
35a90 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b  ls back on the [
35aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35ab0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
35ac0 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69  12962} The [sqli
35ad0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35ae0 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
35af0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
35b00 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
35b10 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
35b20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
35b30 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  th the same.**  
35b40 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
35b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
35b60 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20   or NULL on the 
35b70 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20  first call.**   
35b80 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72         for a par
35b90 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
35ba0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
35bb0 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20 45 61  *.** {F12963} Ea
35bc0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
35bd0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
35be0 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
35bf0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
35c00 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
35c10 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
35c20 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36  ls..**.** {F1296
35c30 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
35c40 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
35c50 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
35c60 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a  ,F,P)] is NULL.*
35c70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
35c80 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  the rollback hoo
35c90 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
35ca0 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
35cb0 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
35cc0 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
35cd0 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
35ce0 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a   rolls back..*/.
35cf0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
35d00 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
35d10 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
35d20 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
35d30 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
35d40 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
35d50 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
35d60 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
35d70 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
35d80 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
35d90 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
35da0 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12970}.**.** The
35db0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
35dc0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
35dd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
35de0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
35df0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
35e00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35e10 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
35e20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35e30 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
35e40 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
35e50 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
35e60 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
35e70 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
35e80 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
35e90 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
35ea0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
35eb0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
35ec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35ed0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
35ee0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
35ef0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
35f00 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
35f10 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
35f20 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
35f30 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
35f40 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
35f50 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
35f60 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
35f70 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
35f80 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
35f90 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
35fa0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
35fb0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
35fc0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
35fd0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35fe0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
35ff0 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
36000 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
36010 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
36020 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
36030 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
36040 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
36050 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65   invoked..** The
36060 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
36070 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
36080 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
36090 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
360a0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
360b0 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
360c0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
360d0 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54  fected row..** T
360e0 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
360f0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
36100 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
36110 72 6f 77 2e 20 49 6e 20 74 68 65 20 63 61 73 65  row. In the case
36120 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64 61 74 65   of.** an update
36130 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 72 6f  , this is the ro
36140 77 69 64 20 61 66 74 65 72 20 74 68 65 20 75 70  wid after the up
36150 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  date takes place
36160 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
36170 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
36180 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
36190 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
361a0 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
361b0 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
361c0 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
361d0 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a  e_sequence)..**.
361e0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
361f0 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36200 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
36210 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75 65  , its pArg value
36220 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 2e  .** is returned.
36230 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
36240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36250 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
36260 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20 54  **.** {F12971} T
36270 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
36280 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
36290 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
362a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
362b0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
362c0 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
362d0 65 64 20 77 69 74 68 20 66 69 72 73 74 20 70 61  ed with first pa
362e0 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e 65 76  rameter P whenev
362f0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
36300 20 74 61 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f   table row is mo
36310 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
36320 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a  , or deleted on.
36330 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
36340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36350 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
36360 46 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c  F12973} The [sql
36370 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36380 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
36390 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ce returns the v
363a0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
363b0 20 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72   of P for the pr
363c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74  evious call on t
363d0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
363e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
363f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
36400 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72  NULL for the fir
36410 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  st call..**.** {
36420 46 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75  F12975} If the u
36430 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62  pdate hook callb
36440 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65  ack F in [sqlite
36450 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
36460 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,P)].**        
36470 20 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74    is NULL then t
36480 68 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c  he no update cal
36490 6c 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e  lbacks are made.
364a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20  .**.** {F12977} 
364b0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
364c0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
364d0 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69  k(D,F,P)] overri
364e0 64 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a  des prior calls.
364f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
36500 68 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63  he same interfac
36510 65 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  e on the same [d
36520 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36530 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
36540 32 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65  2979} The update
36550 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
36560 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
36570 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
36580 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  em.**          t
36590 61 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71  ables such as sq
365a0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
365b0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20  sqlite_sequence 
365c0 61 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  are modified..**
365d0 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65  .** {F12981} The
365e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
365f0 72 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20  r to the update 
36600 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
36610 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b       is one of [
36620 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
36630 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
36640 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
36650 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
36660 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
36670 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
36680 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
36690 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
366a0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33  d..**.** {F12983
366b0 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  } The third and 
366c0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
366d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
366e0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
366f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
36700 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
36710 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77   UTF-8 strings w
36720 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d  hich are the nam
36730 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  es of the.**    
36740 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61        database a
36750 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73  nd table that is
36760 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a   being updated..
36770 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65  .** {F12985} The
36780 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
36790 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
367a0 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
367b0 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20  w after.**      
367c0 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f      the change o
367d0 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ccurs..*/.void *
367e0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
367f0 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
36800 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
36810 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
36820 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
36830 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
36840 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
36850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
36860 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
36870 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
36880 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 20 4b  he {F10330}.** K
36890 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
368a0 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20   cache} {shared 
368b0 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  cache mode}.**.*
368c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  * This routine e
368d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
368e0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
368f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
36900 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
36910 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
36920 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
36930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36940 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
36950 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
36960 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
36970 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
36980 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
36990 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
369a0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
369b0 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a  nt is false..**.
369c0 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67  ** Cache sharing
369d0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
369e0 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
369f0 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20  entire process. 
36a00 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73  {END}.** This is
36a10 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
36a20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
36a30 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76  .5.0. In prior v
36a40 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
36a50 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61  e,.** sharing wa
36a60 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
36a70 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
36a80 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
36a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
36aa0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
36ab0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
36ac0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
36ad0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
36ae0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
36af0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
36b00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
36b10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
36b20 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
36b30 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
36b40 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
36b50 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
36b60 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
36b70 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
36b80 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
36b90 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
36ba0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
36bb0 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
36bc0 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
36bd0 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  e.  When shared.
36be0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
36bf0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
36c00 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
36c10 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
36c20 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
36c30 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
36c40 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
36c50 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
36c60 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
36c70 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
36c80 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
36c90 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
36ca0 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
36cb0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
36cc0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
36cd0 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
36ce0 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
36cf0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
36d00 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
36d10 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
36d20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
36d30 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
36d40 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
36d50 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
36d60 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
36d70 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
36d80 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
36d90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36da0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 31  S:.**.** {F10331
36db0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
36dc0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
36dd0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
36de0 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a  red_cache(B)].**
36df0 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65            will e
36e00 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
36e10 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f   shared cache mo
36e20 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65  de for any subse
36e30 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20  quently.**      
36e40 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74      created [dat
36e50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36e60 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  ] in the same pr
36e70 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ocess..**.** {F1
36e80 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65  0336} When share
36e90 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  d cache is enabl
36ea0 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
36eb0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
36ec0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
36ed0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77  terface will alw
36ee0 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72  ays return an er
36ef0 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33  ror..**.** {F103
36f00 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  37} The [sqlite3
36f10 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
36f20 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61  ache(B)] interfa
36f30 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
36f40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
36f50 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
36f60 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
36f70 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65  r disabled succe
36f80 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ssfully..**.** {
36f90 46 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63  F10339} Shared c
36fa0 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
36fb0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a   by default..*/.
36fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
36fd0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
36fe0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
36ff0 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
37000 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
37010 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a  ry {F17340}.**.*
37020 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
37030 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
37040 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
37050 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
37060 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
37070 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
37080 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
37090 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
370a0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
370b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
370c0 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d  rary. {END}  Mem
370d0 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63 68  ory used to cach
370e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
370f0 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70  ges to improve p
37100 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e  erformance is an
37110 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d   example of non-
37120 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
37130 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c  ..** sqlite3_rel
37140 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65  ease_memory() re
37150 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
37160 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
37170 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69  ly freed,.** whi
37180 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
37190 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68   or less than th
371a0 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
371b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
371c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
371d0 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
371e0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
371f0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  (N)] interface a
37200 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20  ttempts to.**   
37210 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79         free N by
37220 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
37230 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
37240 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
37250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
37260 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
37270 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
37280 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  base library..**
37290 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65  .** {F16342} The
372a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
372b0 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74  e_memory(N)] ret
372c0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  urns the number.
372d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62  **          of b
372e0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
372f0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
37300 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
37310 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
37320 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
37330 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  uested..*/.int s
37340 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37350 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
37360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
37370 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
37380 65 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35 30  eap Size {F17350
37390 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
373a0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
373b0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
373c0 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
373d0 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
373e0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
373f0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
37400 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
37410 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e 20  QLite..** If an 
37420 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
37430 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
37440 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
37450 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  ed the.** soft h
37460 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
37470 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37480 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
37490 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   one or.** more 
374a0 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
374b0 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
374c0 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
374d0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
374e0 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20  **.** The limit 
374f0 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
37500 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71  , because if [sq
37510 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37520 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f  mory()].** canno
37530 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  t free sufficien
37540 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
37550 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
37560 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
37570 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
37580 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
37590 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
375a0 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
375b0 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41  roceeds..**.** A
375c0 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
375d0 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
375e0 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
375f0 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
37600 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
37610 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37620 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
37630 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
37640 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
37650 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ted..** The defa
37660 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
37670 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37680 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t is zero..**.**
37690 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
376a0 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
376b0 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
376c0 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74  ap limit..** But
376d0 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
376e0 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62  p limit cannot b
376f0 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  e honored, execu
37700 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
37710 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
37720 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
37730 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 77 68  ion.  This is wh
37740 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a  y the limit is.*
37750 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74  * called a "soft
37760 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20  " limit.  It is 
37770 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a  advisory only..*
37780 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
37790 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
377a0 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .0, this routine
377b0 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65   only constraine
377c0 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  d the memory.** 
377d0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73  allocated by a s
377e0 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74  ingle thread - t
377f0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
37800 6e 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75  n which this rou
37810 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42  tine.** runs.  B
37820 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51  eginning with SQ
37830 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
37840 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61  .0, the soft hea
37850 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70  p limit is.** ap
37860 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72  plied to all thr
37870 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20  eads. The value 
37880 73 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68  specified for th
37890 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
378a0 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72  t.** is an upper
378b0 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f   bound on the to
378c0 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tal memory alloc
378d0 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68  ation for all th
378e0 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72  reads. In.** ver
378f0 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65  sion 3.5.0 there
37900 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d   is no mechanism
37910 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68   for limiting th
37920 65 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72  e heap usage for
37930 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74  .** individual t
37940 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  hreads..**.** IN
37950 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
37960 7b 46 31 36 33 35 31 7d 20 54 68 65 20 5b 73 71  {F16351} The [sq
37970 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37980 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74 65 72 66  limit(N)] interf
37990 61 63 65 20 70 6c 61 63 65 73 20 61 20 73 6f 66  ace places a sof
379a0 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20  t limit.**      
379b0 20 20 20 20 6f 66 20 4e 20 62 79 74 65 73 20 6f      of N bytes o
379c0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
379d0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
379e0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
379f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73  d.**          us
37a00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
37a10 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
37a20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 61 74  e3_realloc()] at
37a30 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a 20 20 20   any point.**   
37a40 20 20 20 20 20 20 20 69 6e 20 74 69 6d 65 2e 0a         in time..
37a50 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32 7d 20 49  **.** {F16352} I
37a60 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
37a70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
37a80 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
37a90 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20  oc()] would.**  
37aa0 20 20 20 20 20 20 20 20 63 61 75 73 65 20 74 68          cause th
37ab0 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e 74 20 6f  e total amount o
37ac0 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f  f allocated memo
37ad0 72 79 20 74 6f 20 65 78 63 65 65 64 20 74 68 65  ry to exceed the
37ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 6f 66  .**          sof
37af0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68  t heap limit, th
37b00 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  en [sqlite3_rele
37b10 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
37b20 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
37b30 20 20 20 20 20 69 6e 20 61 6e 20 61 74 74 65 6d       in an attem
37b40 70 74 20 74 6f 20 72 65 64 75 63 65 20 74 68 65  pt to reduce the
37b50 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 70 72   memory usage pr
37b60 69 6f 72 20 74 6f 20 70 72 6f 63 65 65 64 69 6e  ior to proceedin
37b70 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  g.**          wi
37b80 74 68 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  th the memory al
37b90 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74  location attempt
37ba0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 33 7d  ..**.** {F16353}
37bb0 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   Calls to [sqlit
37bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
37bd0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
37be0 28 29 5d 20 74 68 61 74 20 74 72 69 67 67 65 72  ()] that trigger
37bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 74  .**          att
37c00 65 6d 70 74 73 20 74 6f 20 72 65 64 75 63 65 20  empts to reduce 
37c10 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 74 68 72  memory usage thr
37c20 6f 75 67 68 20 74 68 65 20 73 6f 66 74 20 68 65  ough the soft he
37c30 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20 20 20 20  ap limit.**     
37c40 20 20 20 20 20 6d 65 63 68 61 6e 69 73 6d 20 63       mechanism c
37c50 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20 69 66 20  ontinue even if 
37c60 74 68 65 20 61 74 74 65 6d 70 74 20 74 6f 20 72  the attempt to r
37c70 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  educe memory.** 
37c80 20 20 20 20 20 20 20 20 20 75 73 61 67 65 20 69           usage i
37c90 73 20 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a  s unsuccessful..
37ca0 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34 7d 20 41  **.** {F16354} A
37cb0 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
37cc0 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 69 6e  o value for N in
37cd0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
37ce0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
37cf0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
37d00 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  N)] means that t
37d10 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 0a  here is no soft.
37d20 2a 2a 20 20 20 20 20 20 20 20 20 20 68 65 61 70  **          heap
37d30 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73 71 6c 69   limit and [sqli
37d40 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37d50 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20  ry()] will only 
37d60 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  be.**          c
37d70 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72  alled when memor
37d80 79 20 69 73 20 63 6f 6d 70 6c 65 74 65 6c 79 20  y is completely 
37d90 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  exhausted..**.**
37da0 20 7b 46 31 36 33 35 35 7d 20 54 68 65 20 64 65   {F16355} The de
37db0 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
37dc0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37dd0 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
37de0 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45 61 63 68  ** {F16358} Each
37df0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37e00 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37e10 74 28 4e 29 5d 20 6f 76 65 72 72 69 64 65 73 20  t(N)] overrides 
37e20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37e30 76 61 6c 75 65 73 20 73 65 74 20 62 79 20 61 6c  values set by al
37e40 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  l prior calls..*
37e50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
37e60 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
37e70 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
37e80 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
37e90 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
37ea0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
37eb0 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12850}.**.** 
37ec0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
37ed0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
37ee0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
37ef0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
37f00 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
37f10 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
37f20 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
37f30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
37f40 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
37f50 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
37f60 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
37f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c 75  ..**.** The colu
37f80 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
37f90 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
37fa0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
37fb0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a   parameters to.*
37fc0 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
37fd0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
37fe0 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20  meter is either 
37ff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
38000 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65  database.** (i.e
38010 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22  . "main", "temp"
38020 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
38030 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
38040 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
38050 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
38060 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e 55  ULL. If it is NU
38070 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74  LL, then all att
38080 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20  ached databases 
38090 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20  are searched.** 
380a0 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73  for the table us
380b0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67  ing the same alg
380c0 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74  orithm used by t
380d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
380e0 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65  ne to.** resolve
380f0 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62   unqualified tab
38100 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a  le references..*
38110 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
38120 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
38130 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
38140 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
38150 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
38160 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
38170 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
38180 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
38190 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
381a0 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
381b0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65  e NULL..**.** Me
381c0 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
381d0 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
381e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
381f0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
38200 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
38210 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
38220 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
38230 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68  ction. Any of th
38240 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
38250 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
38260 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
38270 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
38280 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
38290 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
382a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
382b0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
382c0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
382d0 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68  h> Parameter <th
382e0 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65  > Output<br>Type
382f0 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69   <th>  Descripti
38300 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
38310 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 5th <td> const
38320 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61   char* <td> Data
38330 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64   type.** <tr><td
38340 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 6th <td> const
38350 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65   char* <td> Name
38360 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c   of default coll
38370 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a  ation sequence.*
38380 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c  * <tr><td> 7th <
38390 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
383a0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
383b0 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
383c0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
383d0 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74   <tr><td> 8th <t
383e0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
383f0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
38400 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
38410 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
38420 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74   <tr><td> 9th <t
38430 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
38440 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
38450 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43 52 45 4d  mn is AUTOINCREM
38460 45 4e 54 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ENT.** </table>.
38470 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
38480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
38490 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
384a0 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
384b0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
384c0 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
384d0 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
384e0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
384f0 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
38500 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
38510 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
38520 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
38530 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
38540 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
38550 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
38560 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
38570 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
38580 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73  ..**.** If the s
38590 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
385a0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
385b0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
385c0 6e 64 20 61 6e 0a 2a 2a 20 49 4e 54 45 47 45 52  nd an.** INTEGER
385d0 20 50 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6c   PRIMARY KEY col
385e0 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70  umn has been exp
385f0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
38600 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75  , then the outpu
38610 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  t.** parameters 
38620 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20  are set for the 
38630 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
38640 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74  red column. If t
38650 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78  here is no.** ex
38660 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
38670 64 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  d INTEGER PRIMAR
38680 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 2c 20 74 68  Y KEY column, th
38690 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
386a0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
386b0 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
386c0 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
386d0 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
386e0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
386f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
38700 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
38710 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
38720 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
38730 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
38740 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
38750 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68   </pre>.**.** Th
38760 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
38770 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
38780 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
38790 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
387a0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
387b0 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
387c0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
387d0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
387e0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
387f0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
38800 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
38810 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
38820 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
38830 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
38840 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38850 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
38860 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
38870 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
38880 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49 20  .**.** This API 
38890 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
388a0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
388b0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
388c0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
388d0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
388e0 45 54 41 44 41 54 41 20 43 20 70 72 65 70 72 6f  ETADATA C prepro
388f0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
38900 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
38910 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
38920 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
38930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
38940 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
38950 6e 6e 65 63 74 69 6f 6e 20 68 6