/ Hex Artifact Content
Login

Artifact 2f1fd40e8ba7c0a51eb755e0b6af236ce692325b:


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 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
6040: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
6050: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
6060: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
6070: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
6080: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
6090: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60a0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
60b0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
60c0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
60d0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
60e0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
60f0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
6100: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
6110: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
6120: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
6130: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
6140: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
6150: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
6170: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
6180: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
6190: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
61a0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
61b0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
61c0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
61d0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
61e0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
61f0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
6200: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
6210: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
6220: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
6230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
6240: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
6250: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
6260: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
6270: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6290: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
62a0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
62b0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
62c0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
62d0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
62e0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
62f0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
6300: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
6320: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6340: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
6350: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
6360: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6370: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
6380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6390: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
63a0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
63b0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
63c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
63d0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
63e0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
63f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
6400: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
6410: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
6420: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
6430: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6440: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6450: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6460: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6470: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6480: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6490: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
64a0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
64b0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
64c0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
64d0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
64e0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
64f0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
6500: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
6510: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
6520: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
6530: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6540: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
6550: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
6560: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
6570: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
6580: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
6590: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
65a0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
65b0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
65c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
65d0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
65e0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
65f0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
6600: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
6610: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
6620: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
6630: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
6640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6650: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
6660: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
6670: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
6680: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6690: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
66a0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
66b0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
66c0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
66d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
66e0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
66f0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
6700: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
6710: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
6720: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
6730: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6740: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
6750: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e  .** If the xOpen
6760: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6770: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6780: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6790: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
67a0: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
67b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
67c0: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
67d0: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
67e0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
67f0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64  e xOpen reported
6800: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6810: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6820: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6830: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6840: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6850: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72   xOpen.** is for
6860: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65   the xOpen to se
6870: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
6880: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
6890: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ent to NULL..**.
68a0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
68b0: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
68c0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
68d0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
68e0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
68f0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
6900: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
6910: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
6920: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
6930: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6940: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6950: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6960: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6970: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6980: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6990: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
69a0: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
69b0: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
69c0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
69d0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
69e0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
69f0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
6a00: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6a10: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
6a20: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6a30: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6a40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6a50: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6a60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a70: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6a90: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6ab0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
6ac0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
6ad0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
6ae0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
6af0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
6b00: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
6b10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6b20: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
6b30: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6b40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6b50: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6b60: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6b70: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6b80: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6b90: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6ba0: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6bb0: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
6bc0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
6bd0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
6be0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
6bf0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
6c00: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
6c10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
6c20: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6c30: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6c40: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6c50: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6c60: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6c70: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6c80: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6c90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6ca0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6cb0: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6cc0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6cd0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
6ce0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
6cf0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
6d00: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
6d10: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
6d20: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
6d30: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6d40: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6d50: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6d60: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6d70: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6d80: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6d90: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6da0: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6db0: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
6dc0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
6dd0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
6de0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
6df0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
6e00: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
6e10: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
6e20: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
6e30: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6e40: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6e50: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6e60: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6e70: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6e80: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6e90: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6ea0: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6eb0: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
6ec0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6ed0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6ee0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6ef0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6f00: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6f10: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6f20: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6f30: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6f40: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6f50: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6f60: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6f70: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6f80: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6f90: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6fa0: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6fb0: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
6fc0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
6fd0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
6fe0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
6ff0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
7000: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
7010: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
7020: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
7030: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
7040: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
7050: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
7060: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
7070: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
7080: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
7090: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
70a0: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
70b0: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
70c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
70e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70f0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
7100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7110: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
7120: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7130: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
7140: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7150: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
7160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7170: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
7180: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7190: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
71a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
71b0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
71c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
71d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
71e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
71f0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7200: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
7210: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7220: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
7230: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
7240: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
7250: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
7260: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
7270: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
7280: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7290: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
72a0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
72b0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
72c0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
72d0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
72e0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
72f0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
7300: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
7310: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
7320: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
7330: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
7340: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
7350: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
7360: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
7370: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
7380: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
7390: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
73a0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
73b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
73c0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
73d0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
73e0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
73f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7400: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
7410: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
7420: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
7430: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7440: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7450: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7460: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
7470: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
7480: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
7490: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
74a0: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
74b0: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
74c0: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
74d0: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
74e0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
74f0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
7500: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
7510: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
7520: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
7530: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
7540: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
7550: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
7560: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
7570: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
7580: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7590: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
75a0: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
75b0: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
75c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75d0: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
75e0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
75f0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
7600: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7610: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
7620: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
7630: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7640: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7650: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7660: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
7670: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7680: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7690: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
76a0: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
76b0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
76c0: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
76d0: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
76e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
76f0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
7700: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
7710: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7720: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
7730: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7740: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7750: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7760: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
7770: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7780: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
7790: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
77a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
77b0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
77c0: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
77d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
77e0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
77f0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
7800: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7810: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
7820: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
7830: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7840: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
7850: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7860: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
7870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
7880: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
7890: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
78a0: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
78b0: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
78c0: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
78d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
78e0: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
78f0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
7900: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
7910: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
7920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
7930: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
7940: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
7950: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
7960: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7970: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
7980: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
7990: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
79a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
79b0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
79c0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
79d0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
79e0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
79f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
7a00: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61  eger constants a
7a10: 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74  re opcodes for t
7a20: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7a30: 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
7a40: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a50: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64  hods] object and
7a60: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7a80: 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a  ].** interface..
7a90: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
7aa0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7ab0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7ac0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
7ad0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
7ae0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
7af0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
7b00: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72  to write the cur
7b10: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a  rent state of.**
7b20: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f   the lock (one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  f [SQLITE_LOCK_N
7b40: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  ONE], [SQLITE_LO
7b50: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b  CK_SHARED],.** [
7b60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7b70: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  RVED], [SQLITE_L
7b80: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
7ba0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74  CLUSIVE]).** int
7bb0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61  o an integer tha
7bc0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  t the pArg argum
7bd0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54  ent points to. T
7be0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  his capability.*
7bf0: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  * is used during
7c00: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c   testing and onl
7c10: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
7c20: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
7c30: 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64  ITE_TEST.** is d
7c40: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
7c50: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
7c60: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
7c70: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
7c80: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
7c90: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
7ca0: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
7cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
7cc0: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
7cd0: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
7ce0: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
7cf0: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
7d00: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
7d10: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
7d20: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
7d30: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
7d40: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
7d50: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
7d60: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
7d70: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
7d80: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
7d90: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
7da0: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
7db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
7dc0: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
7de0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
7df0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
7e00: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
7e10: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
7e20: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
7e30: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
7e40: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
7e50: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
7e60: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
7e70: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
7e80: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
7e90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7ea0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
7eb0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
7ec0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
7ed0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
7ee0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
7ef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
7f00: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
7f10: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
7f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
7f30: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
7f40: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
7f50: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
7f60: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
7f70: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
7f80: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
7f90: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
7fa0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
7fb0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7fc0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
7fd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7fe0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
7ff0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
8000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
8010: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
8020: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
8030: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
8040: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8060: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8070: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8080: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8090: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
80a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
80b0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
80c0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
80d0: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
80e0: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
80f0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
8100: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8110: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
8120: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
8130: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
8140: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8150: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
8160: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
8170: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8180: 49 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66  IZE       6.#def
8190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
81a0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
81b0: 20 20 37 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    7.../*.** CAPI
81c0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
81d0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
81e0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
81f0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
8200: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
8210: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
8220: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
8230: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
8240: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
8250: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
8260: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
8270: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
8280: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
8290: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
82a0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
82b0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
82c0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
82d0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
82e0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
82f0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
8300: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
8310: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
8320: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
8330: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
8340: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
8350: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
8360: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
8370: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
8380: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
8390: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
83a0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
83b0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
83c0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
83d0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
83e0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
83f0: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
8400: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
8410: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
8420: 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a  le system"..**.*
8430: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
8440: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
8450: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
8460: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
8470: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
8480: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
8490: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
84a0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
84b0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
84c0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
84d0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
84e0: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
84f0: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
8500: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
8510: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
8520: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
8530: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
8540: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
8550: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
8560: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
8570: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
8580: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
8590: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
85a0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
85b0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
85c0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
85d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
85e0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
85f0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
8600: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
8610: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
8620: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
8630: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
8640: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
8650: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
8660: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
8670: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
8680: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
8690: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
86a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
86b0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
86c0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
86d0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
86e0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
86f0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
8700: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
8710: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
8720: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
8730: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
8740: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
8750: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
8760: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
8770: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
8780: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
8790: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
87a0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
87b0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
87c0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
87d0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
87e0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
87f0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
8800: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
8810: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
8820: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
8830: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
8840: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
8850: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
8860: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
8870: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
8880: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
8890: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
88a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
88b0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
88c0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
88d0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
88e0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
88f0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
8900: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
8910: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
8920: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
8930: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
8940: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  modules..**.** ^
8950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
8960: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
8970: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
8980: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
8990: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
89a0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
89b0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
89c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
89d0: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
89e0: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
89f0: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
8a00: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
8a10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8a20: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
8a30: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
8a40: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
8a50: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
8a60: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61  ore than.** 10 a
8a70: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
8a80: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
8a90: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
8aa0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
8ab0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
8ac0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
8ad0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
8ae0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
8af0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
8b00: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
8b10: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
8b20: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
8b30: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
8b40: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
8b50: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
8b60: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
8b70: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
8b80: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
8b90: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
8ba0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8bb0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
8bc0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8bd0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8be0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
8bf0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8c00: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8c10: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
8c20: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8c30: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8c40: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8c50: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8c60: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8c70: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8c80: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8c90: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8ca0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8cb0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8cc0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8cd0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8ce0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8cf0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8d00: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8d10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8d20: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8d30: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8d40: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8d50: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8d70: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8d80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8d90: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8da0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8db0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8dc0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8dd0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8de0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8df0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8e00: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8e10: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8e20: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
8e30: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
8e40: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8e50: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8e60: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
8e70: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
8e80: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
8e90: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
8ea0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8eb0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
8ec0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8ed0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
8ee0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ef0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
8f00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
8f20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8f30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8f40: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
8f50: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
8f60: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
8f70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8f80: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
8f90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8fa0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
8fb0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
8fc0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
8fd0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
8fe0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
8ff0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
9000: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
9010: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
9020: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
9030: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
9040: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
9050: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
9060: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
9070: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
9080: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
9090: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
90a0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
90b0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
90c0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
90d0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
90e0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
90f0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
9100: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
9110: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
9120: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
9130: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
9140: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
9150: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
9160: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
9170: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
9180: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
9190: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
91a0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
91b0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
91c0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
91d0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
91e0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
91f0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
9200: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
9210: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
9220: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
9230: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9240: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
9250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
9260: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
9270: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
9280: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
9290: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
92a0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
92b0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
92c0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
92d0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
92e0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
92f0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
9300: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
9310: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
9320: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
9330: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
9340: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
9350: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
9360: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
9370: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
9380: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
9390: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
93a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
93b0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
93c0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
93d0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
93e0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
93f0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
9400: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
9410: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
9420: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
9430: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
9440: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
9450: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
9460: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
9470: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9480: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
9490: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
94a0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
94b0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
94c0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
94d0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
94e0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
94f0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
9500: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
9510: 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
9520: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
9530: 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
9540: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
9550: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
9560: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
9570: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
9580: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9590: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
95a0: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
95b0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
95c0: 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
95d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
95e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
95f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
9600: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
9610: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
9620: 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
9630: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
9640: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
9650: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
9660: 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
9670: 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
9680: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
9690: 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
96a0: 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
96b0: 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
96c0: 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
96d0: 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
96e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
96f0: 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
9700: 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
9710: 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
9720: 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
9730: 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
9740: 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
9750: 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
9760: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ..**.** ^The fla
9770: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
9780: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
9790: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
97a0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
97b0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
97c0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
97d0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
97e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
97f0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
9800: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
9810: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
9820: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9830: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
9840: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
9850: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
9860: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
9870: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
9880: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
9890: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
98a0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
98b0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
98c0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
98d0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
98e0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
98f0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9900: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9910: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9920: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9930: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9940: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9950: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9960: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9970: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
9980: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
9990: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
99a0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
99b0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
99c0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
99d0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
99e0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
99f0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9a00: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9a10: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9a20: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9a30: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9a40: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9a50: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9a60: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9a70: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9a80: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
9a90: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
9aa0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9ab0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9ac0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9ad0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9ae0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9af0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9b00: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9b10: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9b20: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9b30: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9b40: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
9b50: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
9b60: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
9b70: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9b80: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9b90: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9ba0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9bb0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9bc0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9bd0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9be0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9bf0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9c00: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9c10: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9c20: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9c30: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
9c40: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
9c50: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
9c60: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
9c70: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
9c80: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
9c90: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
9ca0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
9cb0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
9cc0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
9cd0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
9ce0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
9cf0: 6c 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  led by 86400000 
9d00: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
9d10: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
9d20: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
9d30: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
9d40: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
9d50: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
9d60: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
9d70: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
9d80: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
9d90: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
9da0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
9db0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
9dc0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
9dd0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
9de0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
9df0: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
9e00: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
9e10: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
9e20: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
9e30: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f   unavailable..*/
9e40: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9e50: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
9e60: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
9e70: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
9e80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
9e90: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
9ea0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
9eb0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
9ec0: 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  2) */.  int szOs
9ed0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9ee0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9ef0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9f00: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9f10: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9f20: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9f30: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9f40: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9f50: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
9f60: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
9f70: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
9f80: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
9f90: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
9fa0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
9fb0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9fc0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9fd0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9fe0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9ff0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a000: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a010: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a020: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a030: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a040: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a050: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a060: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a070: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a080: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a090: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a0a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a0b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a0c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a0d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a0e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a0f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a100: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a110: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a120: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a130: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a140: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a150: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a160: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a170: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a180: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a190: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a1a0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a1b0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
a1c0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
a1d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
a1e0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a1f0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
a200: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
a210: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a220: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
a230: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
a240: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
a250: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
a260: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
a270: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
a280: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
a290: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
a2a0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
a2b0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
a2c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
a2d0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
a2e0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
a2f0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
a300: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a310: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a320: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
a330: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
a340: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
a350: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
a360: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
a370: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
a380: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
a390: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
a3a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
a3b0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
a3c0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
a3d0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
a3e0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
a3f0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
a400: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
a410: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
a420: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
a430: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
a440: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
a450: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
a460: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
a470: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
a480: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
a490: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
a4a0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
a4b0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
a4c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
a4d0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
a4e0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
a4f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
a500: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
a510: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
a520: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
a530: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
a540: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
a550: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
a560: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
a570: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
a580: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a590: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
a5a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
a5b0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
a5c0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
a5d0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
a5e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
a5f0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
a600: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a610: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a620: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
a630: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
a640: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
a650: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
a660: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
a670: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
a680: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
a690: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
a6a0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
a6b0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
a6c0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
a6d0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
a6e0: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
a6f0: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
a700: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
a710: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
a720: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
a730: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
a740: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a750: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
a760: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
a770: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
a780: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
a790: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
a7a0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
a7b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
a7c0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
a7d0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
a7e0: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
a7f0: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
a800: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
a810: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
a820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a830: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
a840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
a850: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
a860: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
a870: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
a880: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a8a0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
a8b0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
a8c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
a8d0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
a8e0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
a8f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a900: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
a910: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
a920: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
a930: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
a940: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
a950: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
a960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
a970: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
a980: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
a990: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
a9a0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
a9b0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
a9c0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
a9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
a9e0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
a9f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
aa00: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aa10: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
aa20: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
aa30: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
aa40: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
aa50: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
aa60: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
aa70: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
aa80: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
aa90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
aaa0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
aab0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
aac0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
aad0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
aae0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
aaf0: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   no the correspo
ab00: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
ab10: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
ab20: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
ab30: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
ab40: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
ab50: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
ab60: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
ab70: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
ab80: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
ab90: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
aba0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
abb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
abc0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
abd0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
abe0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
abf0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ac00: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ac10: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
ac20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
ac30: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
ac40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
ac50: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
ac60: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
ac70: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
ac80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ac90: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
aca0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
acb0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
acc0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
acd0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
ace0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
acf0: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
ad00: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
ad10: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
ad20: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
ad30: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
ad40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ad50: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
ad60: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
ad70: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
ad80: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
ad90: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ada0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
adb0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
adc0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
add0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
ade0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
adf0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
ae00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
ae10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
ae20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
ae30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ae40: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
ae50: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
ae60: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
ae70: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
ae80: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
ae90: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
aea0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
aeb0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
aec0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
aed0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
aee0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
aef0: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
af00: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
af10: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
af20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
af30: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
af40: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
af50: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
af60: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
af70: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
af80: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
af90: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
afa0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
afb0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
afc0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
afd0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
afe0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
aff0: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
b000: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b010: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
b020: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
b030: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
b040: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
b050: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
b060: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
b070: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
b080: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
b090: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
b0a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
b0b0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
b0c0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
b0d0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
b0e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
b0f0: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
b100: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
b110: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
b120: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
b130: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
b140: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
b150: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
b160: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
b170: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
b180: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
b190: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
b1a0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
b1b0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b1c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b1d0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
b1e0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
b1f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
b200: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
b210: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
b220: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
b230: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
b240: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
b250: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
b260: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
b270: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
b280: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
b290: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
b2a0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
b2b0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
b2c0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
b2d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
b2e0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
b2f0: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
b300: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
b310: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
b320: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
b330: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
b340: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
b350: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
b360: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
b370: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
b380: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
b390: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
b3a0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
b3b0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
b3c0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
b3d0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
b3e0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b3f0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
b400: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
b410: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
b420: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
b430: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
b440: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
b450: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
b460: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
b470: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
b480: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
b490: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b4a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b4b0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
b4c0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
b4d0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
b4e0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
b4f0: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
b500: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
b510: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
b520: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
b530: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b540: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
b550: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
b560: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
b570: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
b580: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
b590: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b5a0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
b5b0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
b5c0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
b5d0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
b5e0: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
b5f0: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
b600: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
b610: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
b620: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b630: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
b640: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
b650: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b660: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
b670: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
b680: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b690: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
b6a0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
b6b0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
b6c0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
b6d0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b6e0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
b6f0: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
b700: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
b710: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
b720: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
b730: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
b740: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
b750: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
b760: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b770: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
b780: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
b790: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
b7a0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
b7b0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
b7c0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
b7d0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
b7e0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
b7f0: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
b800: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
b810: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
b820: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
b830: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
b840: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
b850: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
b860: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
b870: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
b880: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b890: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
b8a0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
b8b0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
b8c0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
b8d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
b8e0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
b8f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
b900: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
b910: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
b920: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
b930: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
b940: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
b950: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
b960: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
b970: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
b980: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
b990: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
b9a0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
b9b0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
b9c0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
b9d0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
b9e0: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
b9f0: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
ba00: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
ba10: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
ba20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ba30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
ba40: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
ba50: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
ba60: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
ba70: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
ba80: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
ba90: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
baa0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
bab0: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
bac0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bad0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
bae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
baf0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bb00: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
bb10: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
bb20: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
bb30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
bb40: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
bb50: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
bb60: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
bb70: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
bb80: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
bb90: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
bba0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
bbb0: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
bbc0: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
bbd0: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
bbe0: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
bbf0: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
bc00: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
bc10: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
bc20: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
bc30: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
bc40: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
bc50: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
bc60: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
bc70: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
bc80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
bc90: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
bca0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bcb0: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
bcc0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
bcd0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
bce0: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
bcf0: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
bd00: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
bd10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
bd20: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
bd30: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
bd40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
bd50: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
bd60: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
bd70: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
bd80: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
bd90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bda0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
bdb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
bdc0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
bdd0: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
bde0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
bdf0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
be00: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
be10: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
be20: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
be30: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
be40: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
be50: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
be60: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
be70: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
be80: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
be90: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
bea0: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
beb0: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
bec0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
bed0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
bee0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
bef0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
bf00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
bf10: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
bf20: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
bf30: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
bf40: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
bf50: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
bf60: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
bf70: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
bf80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bf90: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
bfa0: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
bfb0: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
bfc0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
bfd0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
bfe0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
bff0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
c000: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
c010: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
c020: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
c030: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
c040: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
c050: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
c060: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
c070: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
c080: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
c090: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
c0a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c0b0: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
c0c0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
c0d0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
c0e0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
c0f0: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
c100: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
c110: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
c120: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
c130: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
c140: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
c150: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
c160: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
c170: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
c180: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
c190: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
c1a0: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
c1b0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
c1c0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
c1d0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
c1e0: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
c1f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
c200: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
c210: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
c220: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
c230: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
c240: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
c250: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
c260: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
c270: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
c280: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
c290: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
c2a0: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
c2b0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
c2c0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
c2d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c2e0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c2f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
c300: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c310: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
c320: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
c330: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
c340: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
c350: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
c360: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
c370: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
c380: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
c390: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
c3a0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
c3b0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
c3c0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
c3d0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
c3e0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c3f0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
c400: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c410: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
c420: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c430: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
c440: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
c450: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
c460: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
c470: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
c480: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
c490: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
c4a0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
c4b0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
c4c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c4d0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
c4e0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
c4f0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
c500: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c510: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
c520: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
c530: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
c540: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c550: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
c560: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
c570: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
c580: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
c590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
c5a0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
c5b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
c5c0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
c5d0: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
c5e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c5f0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
c600: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
c610: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
c620: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
c630: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
c640: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
c650: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
c660: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
c670: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
c680: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c690: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
c6a0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
c6b0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
c6c0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
c6d0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
c6e0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
c6f0: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
c700: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
c710: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c720: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c730: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
c740: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
c750: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
c760: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
c770: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
c780: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
c790: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
c7a0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
c7b0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
c7c0: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
c7d0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
c7e0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
c7f0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
c800: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
c810: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
c820: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
c830: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c840: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c850: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c860: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c870: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c880: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c890: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c8a0: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c8b0: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c8c0: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c8d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c8e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c8f0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c900: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c910: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c920: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c930: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c950: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c960: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
c970: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
c980: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
c990: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
c9a0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c9b0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
c9c0: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
c9d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
c9e0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c9f0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
ca00: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
ca10: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
ca20: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
ca30: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
ca40: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
ca50: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
ca60: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
ca70: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
ca80: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
ca90: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
caa0: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
cab0: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
cac0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
cad0: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
cae0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
caf0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cb00: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cb10: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
cb20: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
cb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
cb40: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cb50: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
cb60: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cb70: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cb80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cb90: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cba0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cbb0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cbc0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cbd0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cbe0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cbf0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cc00: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cc10: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cc20: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cc30: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cc40: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cc50: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cc60: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
cc70: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
cc80: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
cc90: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
cca0: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
ccb0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
ccc0: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
ccd0: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
cce0: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
ccf0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
cd00: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
cd10: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
cd20: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
cd30: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
cd40: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
cd50: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
cd60: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
cd70: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
cd80: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
cd90: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
cda0: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
cdb0: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
cdc0: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
cdd0: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
cde0: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
cdf0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
ce00: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ce10: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
ce20: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
ce30: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
ce40: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
ce50: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
ce60: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
ce70: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
ce80: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
ce90: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
cea0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
ceb0: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
cec0: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
ced0: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
cee0: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
cef0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
cf00: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
cf10: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
cf20: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
cf30: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
cf40: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
cf50: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
cf60: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
cf70: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
cf80: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
cf90: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cfa0: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
cfb0: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
cfc0: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
cfd0: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
cfe0: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
cff0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
d000: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
d010: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
d020: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
d030: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d040: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
d050: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
d060: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
d070: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d080: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
d090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
d0a0: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
d0b0: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
d0c0: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
d0d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
d0e0: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
d0f0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
d100: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
d110: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
d120: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
d130: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
d140: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
d150: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d160: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
d170: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
d180: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
d190: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
d1a0: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
d1b0: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
d1c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
d1d0: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
d1e0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
d1f0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
d200: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
d210: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
d220: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
d230: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
d240: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
d250: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
d260: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
d270: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
d280: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
d290: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
d2a0: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
d2b0: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
d2c0: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
d2d0: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
d2e0: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
d2f0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
d300: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
d310: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
d320: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
d330: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
d340: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
d350: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
d360: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
d370: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
d380: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
d390: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
d3a0: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
d3b0: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
d3c0: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
d3d0: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
d3e0: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
d3f0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
d400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
d410: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
d420: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
d430: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
d440: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
d450: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
d460: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
d470: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
d480: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
d490: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
d4a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d4b0: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
d4c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d4d0: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
d4e0: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
d4f0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
d500: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
d510: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
d520: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
d530: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
d540: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
d550: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
d560: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
d570: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
d580: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
d590: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
d5a0: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
d5b0: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
d5c0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
d5d0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
d5e0: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
d5f0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
d600: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
d610: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
d620: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
d630: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d640: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d650: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d660: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
d670: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
d680: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
d690: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
d6a0: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
d6b0: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
d6c0: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
d6d0: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
d6e0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
d6f0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
d700: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
d710: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
d720: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
d730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
d740: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
d750: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
d760: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
d770: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
d780: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
d790: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
d7a0: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
d7b0: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
d7c0: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
d7d0: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
d7e0: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
d7f0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
d800: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d810: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d820: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
d830: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
d840: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
d850: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d860: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
d870: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
d880: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
d890: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
d8a0: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
d8b0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d8c0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
d8d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
d8e0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
d8f0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
d900: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
d910: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d920: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
d930: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
d940: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
d950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
d970: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
d980: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d990: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
d9a0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
d9b0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
d9c0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
d9d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d9e0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
d9f0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
da00: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
da10: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
da20: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
da30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
da40: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
da50: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
da60: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
da70: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
da80: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
da90: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
daa0: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
dab0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
dac0: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
dad0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
dae0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
daf0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
db00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
db10: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
db30: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
db40: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
db50: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
db60: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
db70: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
db80: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
db90: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
dba0: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
dbb0: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
dbc0: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
dbd0: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
dbe0: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
dbf0: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
dc00: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
dc10: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dc20: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dc30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dc40: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dc50: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc60: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc70: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc80: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
dc90: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
dca0: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
dcb0: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
dcc0: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
dcd0: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
dce0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
dcf0: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
dd00: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
dd10: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
dd20: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
dd30: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
dd40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
dd50: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
dd60: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
dd70: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
dd80: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
dd90: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
dda0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
ddb0: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ddc0: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
ddd0: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
dde0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
ddf0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
de00: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
de10: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
de20: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
de30: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
de40: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
de50: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
de60: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
de70: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
de80: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
de90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dea0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
deb0: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
dec0: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
ded0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
dee0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
def0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
df00: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
df10: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
df20: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
df30: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
df40: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
df50: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
df60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
df70: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
df80: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
df90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
dfa0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
dfb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
dfc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
dfd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
dfe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
dff0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e000: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
e010: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
e020: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
e030: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e040: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
e050: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
e060: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
e070: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
e080: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
e090: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e0a0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
e0b0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e0c0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
e0d0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
e0e0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
e0f0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
e100: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
e110: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
e120: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
e130: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
e140: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
e150: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
e160: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
e170: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
e180: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
e190: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e1a0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
e1b0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
e1c0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
e1d0: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
e1e0: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
e1f0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
e200: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
e210: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e220: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
e230: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
e240: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
e250: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
e260: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e270: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e280: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
e290: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
e2a0: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
e2b0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
e2c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e2d0: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
e2e0: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
e2f0: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
e300: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
e310: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
e320: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
e330: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e340: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e350: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e360: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e370: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e380: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e390: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e3a0: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
e3b0: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
e3c0: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
e3d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e3e0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
e3f0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
e400: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
e410: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
e420: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
e430: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e440: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e450: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
e460: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
e470: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e480: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e490: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e4a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e4b0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
e4c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e4d0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e4e0: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
e4f0: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
e500: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
e510: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
e520: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e530: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
e540: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
e550: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e560: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e570: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
e580: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
e590: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
e5a0: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
e5b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
e5c0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e5d0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
e5e0: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
e5f0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
e600: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
e610: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e620: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
e630: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e640: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e650: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e660: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e670: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e680: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e690: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
e6a0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e6b0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
e6c0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
e6d0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
e6e0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
e6f0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
e700: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e710: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
e720: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
e730: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
e740: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
e750: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e760: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
e770: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
e780: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
e790: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
e7a0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
e7b0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
e7c0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
e7d0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e7e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e7f0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
e800: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
e810: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
e820: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
e830: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
e840: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
e850: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
e860: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
e870: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
e880: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e890: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
e8a0: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
e8b0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e8c0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e8d0: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
e8e0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
e8f0: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
e900: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
e910: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
e920: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e930: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
e940: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
e950: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
e960: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e970: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
e980: 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
e990: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
e9a0: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
e9b0: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
e9c0: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e9d0: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
e9e0: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
e9f0: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
ea00: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
ea10: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
ea20: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
ea30: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
ea40: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
ea50: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
ea60: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
ea70: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
ea80: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
ea90: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
eaa0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
eab0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
eac0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
ead0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
eae0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
eaf0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
eb00: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
eb10: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
eb20: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
eb30: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
eb40: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
eb50: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
eb60: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
eb70: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
eb80: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
eb90: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
eba0: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
ebb0: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
ebc0: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
ebd0: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
ebe0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
ebf0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
ec00: 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54  iple of 16..** T
ec10: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ec20: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
ec30: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
ec40: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
ec50: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
ec60: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
ec70: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
ec80: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
ec90: 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63   than two scratc
eca0: 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68  h buffers per th
ecb0: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
ecc0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
ecd0: 74 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74  twice the expect
ece0: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ecf0: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a  r of threads..**
ed00: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
ed10: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
ed20: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
ed30: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
ed40: 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
ed50: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
ed60: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
ed70: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
ed80: 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
ed90: 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
eda0: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
edb0: 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
edc0: 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
edd0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
ede0: 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
edf0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
ee00: 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
ee10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ee20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ee30: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
ee40: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
ee50: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
ee60: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
ee70: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
ee80: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
ee90: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
eea0: 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
eeb0: 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
eec0: 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e  he implemenation
eed0: 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
eee0: 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
eef0: 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
ef00: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ef10: 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
ef20: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
ef30: 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
ef40: 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
ef50: 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69  NFIG_PCACHE opti
ef60: 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
ef70: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
ef80: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
ef90: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
efa0: 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
efb0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
efc0: 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
efd0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
efe0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
eff0: 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
f000: 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
f010: 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
f020: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
f030: 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
f040: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
f050: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
f060: 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
f070: 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
f080: 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
f090: 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
f0a0: 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
f0b0: 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
f0c0: 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
f0d0: 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
f0e0: 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
f0f0: 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
f100: 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
f110: 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
f120: 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
f130: 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
f140: 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
f150: 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
f160: 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
f170: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
f180: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
f190: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
f1a0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
f1b0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
f1c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
f1d0: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
f1e0: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
f1f0: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
f200: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
f210: 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
f220: 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
f230: 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
f240: 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
f250: 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
f260: 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
f270: 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
f280: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
f290: 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
f2a0: 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
f2b0: 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
f2c0: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
f2d0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f2e0: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
f2f0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
f300: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
f310: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
f320: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
f330: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
f340: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f350: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
f360: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
f370: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
f380: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
f390: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
f3a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
f3b0: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
f3c0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
f3d0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f3e0: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
f3f0: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
f400: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f410: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
f420: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
f430: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
f440: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
f450: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
f460: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
f470: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
f480: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
f490: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
f4a0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
f4b0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
f4c0: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
f4d0: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
f4e0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f4f0: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
f500: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
f510: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
f520: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
f530: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f540: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
f550: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
f560: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
f570: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
f580: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
f590: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f5a0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
f5b0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
f5c0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
f5d0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
f5e0: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
f5f0: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
f600: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
f610: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
f620: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
f630: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
f640: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
f650: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
f660: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
f670: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
f680: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
f690: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
f6a0: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
f6b0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f6c0: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
f6d0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
f6e0: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
f6f0: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
f700: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f710: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f720: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
f730: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f740: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
f750: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
f760: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
f770: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
f780: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f790: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f7a0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
f7b0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
f7c0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
f7d0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
f7e0: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
f7f0: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
f800: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
f810: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
f820: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
f830: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
f840: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
f850: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
f860: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
f870: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
f880: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
f890: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f8a0: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
f8b0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
f8c0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
f8d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f8e0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
f8f0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
f900: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
f910: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
f920: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
f930: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
f940: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
f950: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
f960: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f970: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
f980: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
f990: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
f9a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
f9b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f9c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
f9d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f9e0: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
f9f0: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
fa00: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
fa10: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
fa20: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
fa30: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
fa40: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
fa50: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
fa60: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
fa70: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
fa80: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
fa90: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
faa0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
fab0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
fac0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
fad0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
fae0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
faf0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
fb00: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
fb10: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
fb20: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
fb30: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
fb40: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
fb50: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
fb60: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
fb70: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
fb80: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
fb90: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
fba0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
fbb0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
fbc0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
fbd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fbe0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
fbf0: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
fc00: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
fc10: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
fc20: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
fc30: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
fc40: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
fc50: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
fc60: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
fc70: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fc80: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
fc90: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
fca0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fcb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fcc0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
fcd0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fce0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
fcf0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
fd00: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
fd10: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
fd20: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
fd30: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
fd40: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
fd50: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
fd60: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
fd70: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fd80: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
fd90: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
fda0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
fdb0: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
fdc0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
fdd0: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
fde0: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
fdf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
fe00: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
fe10: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
fe20: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
fe30: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
fe40: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
fe50: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
fe60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
fe70: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
fe80: 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
fe90: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
fea0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
feb0: 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
fec0: 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
fed0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fee0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
fef0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
ff00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
ff10: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
ff20: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
ff30: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
ff40: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
ff50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
ff60: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
ff70: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
ff80: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
ff90: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
ffa0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
ffb0: 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
ffc0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
ffd0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
ffe0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
fff0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
10000 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
10010 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
10020 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
10030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10040 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10050 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10060 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10070 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
10080 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
10090 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
100a0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
100b0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
100c0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
100d0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
100e0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
100f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10100 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
10110 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
10120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10130 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
10140 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
10150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
10160 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
10170 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
10180 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
10190 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
101a0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
101b0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
101c0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
101d0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
101e0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
101f0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
10200 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
10210 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
10220 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
10230 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
10240 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
10250 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
10260 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
10270 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
10280 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
10290 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
102a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
102b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
102c0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
102d0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
102e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
102f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
10300 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
10310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
10320 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
10330 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
10340 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
10350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
10360 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
10370 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
10380 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10390 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
103a0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
103b0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
103c0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
103d0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
103e0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
103f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
10400 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
10410 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
10420 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
10430 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
10440 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
10450 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
10460 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
10470 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
10480 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
10490 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
104a0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
104b0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
104c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
104d0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
104e0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
104f0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
10500 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
10510 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
10520 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
10530 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
10540 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
10550 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
10560 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
10570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10580 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
10590 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
105a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
105b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
105c0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
105d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
105e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
105f0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
10600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10610 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10620 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
10630 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10640 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10660 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
10670 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
10680 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
10690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
106a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
106b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
106c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
106d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
106e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
106f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
10700 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
10710 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10720 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
10730 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
10740 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
10750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10760 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
10770 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
10780 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
10790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
107a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
107b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
107c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
107d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
107e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
107f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
10800 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10810 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
10820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
10830 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
10840 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
10850 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
10860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
10870 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
10880 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
10890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
108a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
108b0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
108c0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
108d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
108e0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
108f0 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
10900 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
10910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10920 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
10930 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
10940 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
10950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
10960 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
10970 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10980 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
10990 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
109a0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
109b0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
109c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
109d0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
109e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
109f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
10a00 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
10a10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10a20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10a30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10a40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10a50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10a60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10a70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10a80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
10a90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
10aa0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
10ab0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
10ac0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
10ad0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
10ae0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
10af0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
10b00 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
10b10 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
10b20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10b30 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10b40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10b50 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10b60 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10b70 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10b80 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10b90 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10ba0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10bb0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
10bc0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10bd0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
10be0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
10bf0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
10c00 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
10c10 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10c20 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
10c30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10c40 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
10c50 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
10c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
10c70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
10c80 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
10c90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
10ca0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10cb0 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
10cc0 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
10cd0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
10ce0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
10cf0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
10d00 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
10d10 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
10d20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10d30 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
10d40 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
10d50 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
10d60 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
10d70 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
10d80 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
10d90 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
10da0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
10db0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
10dc0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
10dd0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
10de0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
10df0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
10e00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
10e10 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
10e20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
10e30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10e40 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
10e50 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
10e60 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
10e70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
10e80 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
10e90 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
10ea0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
10eb0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
10ec0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
10ed0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10ee0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
10ef0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10f00 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
10f10 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
10f20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
10f30 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
10f40 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
10f50 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
10f60 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
10f70 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
10f80 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
10f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10fa0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
10fb0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
10fc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
10fd0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
10fe0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
10ff0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
11000 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
11010 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
11020 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
11030 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
11040 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
11050 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
11060 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
11070 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
11080 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
11090 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
110a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
110b0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
110c0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
110d0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
110e0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
110f0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
11100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
11110 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
11120 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
11130 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11140 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
11150 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
11160 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
11170 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
11180 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
11190 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
111a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
111b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
111c0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
111d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
111e0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
111f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11200 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
11210 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
11220 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
11230 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
11240 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11250 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
11260 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
11270 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
11280 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11290 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
112a0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
112b0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
112c0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
112d0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
112e0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
112f0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
11300 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
11310 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
11320 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
11330 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
11340 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
11350 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
11360 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
11370 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
11380 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
11390 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
113a0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
113b0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
113c0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
113d0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
113e0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
113f0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
11400 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
11410 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
11420 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
11430 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
11440 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
11450 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
11460 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
11470 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
11480 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
11490 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
114a0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
114b0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
114c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
114d0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
114e0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
114f0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
11500 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
11510 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
11520 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
11530 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
11540 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
11550 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
11560 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
11570 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
11580 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
11590 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
115a0 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
115b0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
115c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
115d0 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
115e0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
115f0 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
11600 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
11610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
11620 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
11630 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
11640 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
11650 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
11660 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
11670 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
11680 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
11690 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
116a0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
116b0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
116c0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
116d0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
116e0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
116f0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
11700 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
11710 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
11720 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
11730 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
11740 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
11750 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
11760 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
11770 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
11780 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
11790 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
117a0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
117b0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
117c0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
117d0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
117e0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
117f0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
11800 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
11810 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
11820 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
11830 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
11840 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
11850 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
11860 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
11870 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
11880 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
11890 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
118a0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
118b0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
118c0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
118d0 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
118e0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
118f0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
11900 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
11910 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
11920 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
11930 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
11940 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
11950 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
11960 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
11970 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
11990 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
119a0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
119b0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
119c0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
119d0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
119e0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
119f0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
11a00 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
11a10 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
11a20 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
11a30 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
11a40 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
11a50 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
11a60 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
11a70 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
11a80 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
11a90 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11aa0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
11ab0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
11ac0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
11ad0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11ae0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
11af0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
11b00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11b10 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11b20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
11b30 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
11b40 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11b50 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11b60 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11b70 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
11b80 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
11b90 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
11ba0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
11bb0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
11bc0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11bd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11be0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11c00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11c10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11c20 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11c30 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11c40 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
11c50 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
11c60 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
11c70 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
11c80 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
11c90 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
11ca0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
11cb0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
11cc0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11cd0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11ce0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11cf0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11d00 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11d10 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11d20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11d30 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11d40 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
11d50 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
11d60 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
11d70 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
11d80 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
11d90 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
11da0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
11db0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
11dc0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11dd0 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11de0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11df0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11e00 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11e10 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11e20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11e30 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11e40 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11e50 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11e60 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
11e70 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
11e80 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
11e90 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
11ea0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11eb0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
11ec0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
11ed0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
11ee0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
11ef0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
11f00 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
11f10 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
11f20 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
11f30 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
11f40 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
11f50 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
11f60 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
11f70 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
11f80 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
11f90 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
11fa0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
11fb0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
11fc0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
11fd0 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
11fe0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
11ff0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
12000 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
12010 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
12020 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
12030 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
12040 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
12050 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
12060 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
12070 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
12080 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
12090 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
120a0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
120b0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
120c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
120d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
120e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
120f0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
12100 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
12110 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
12120 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
12130 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
12140 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
12150 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
12160 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
12170 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
12180 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
12190 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
121a0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
121b0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
121c0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
121d0 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
121e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
121f0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
12200 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
12210 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
12220 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
12230 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
12240 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
12250 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
12260 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
12270 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
12280 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
12290 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
122a0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
122b0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
122c0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
122d0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
122e0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
122f0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
12300 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
12310 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
12320 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
12330 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
12340 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
12350 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
12360 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
12370 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
12380 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
12390 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
123a0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
123b0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
123c0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
123d0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
123e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
123f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
12400 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12410 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12420 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12430 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
12440 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
12450 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
12460 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
12470 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
12480 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12490 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
124a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
124b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
124c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
124d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
124e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
124f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
12500 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
12510 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
12530 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
12540 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
12550 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12560 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12570 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
12580 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
12590 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
125a0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
125b0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
125c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
125d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
125e0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
125f0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
12600 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
12610 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
12620 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
12630 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
12640 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
12650 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
12660 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
12670 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
12680 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
12690 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
126a0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
126b0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
126c0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
126d0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
126e0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
126f0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
12700 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
12710 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
12720 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
12730 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
12740 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
12750 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
12760 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
12770 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
12780 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
12790 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
127a0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
127b0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
127c0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
127d0 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
127e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
127f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
12800 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
12810 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
12820 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
12830 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
12840 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
12850 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
12860 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
12870 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
12880 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
12890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
128a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
128b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
128c0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
128d0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
128e0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
128f0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
12900 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
12910 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12920 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12930 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12940 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
12950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12960 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
12970 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12980 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
12990 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
129a0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
129b0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
129c0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
129d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
129e0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
129f0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12a00 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
12a10 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
12a20 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
12a30 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
12a40 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
12a50 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
12a60 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
12a70 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
12a80 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
12a90 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
12aa0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
12ab0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
12ac0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
12ad0 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
12ae0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
12af0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
12b00 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
12b10 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
12b20 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
12b30 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
12b40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
12b50 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12b60 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
12b70 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
12b80 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
12b90 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
12ba0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
12bb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
12bc0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12bd0 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12be0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12bf0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12c00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12c10 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12c20 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12c30 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12c40 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
12c50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
12c60 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
12c70 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
12c80 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
12c90 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
12ca0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12cb0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
12cc0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12cd0 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12ce0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12cf0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12d00 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12d10 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12d20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12d30 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12d40 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
12d50 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12d60 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
12d70 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
12d80 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
12d90 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
12da0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
12db0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
12dc0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12dd0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12de0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12df0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12e00 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12e10 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12e20 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12e30 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12e40 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12e50 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12e60 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
12e70 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
12e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12e90 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
12ea0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
12eb0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
12ec0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12ed0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12ee0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
12ef0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
12f00 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12f10 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
12f20 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
12f30 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
12f40 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
12f50 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
12f60 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12f70 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
12f80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12f90 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12fa0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
12fb0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
12fc0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12fd0 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
12fe0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
12ff0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
13000 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
13010 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
13020 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
13030 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
13040 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
13050 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
13060 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
13070 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
13080 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
13090 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
130a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
130b0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
130c0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
130d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
130e0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
130f0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
13100 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
13110 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
13120 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
13130 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
13140 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
13150 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
13160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13170 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13180 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13190 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
131a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
131b0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
131c0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
131d0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
131e0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
131f0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13200 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
13210 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
13220 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
13230 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
13240 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
13250 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
13260 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
13270 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
13280 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
13290 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
132a0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
132b0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
132c0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
132d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
132e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
132f0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
13300 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
13310 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
13320 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
13330 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
13340 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
13350 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
13360 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
13370 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
13380 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
13390 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
133a0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
133b0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
133c0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
133d0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
133e0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
133f0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13400 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
13410 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
13420 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
13430 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
13440 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
13450 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
13460 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
13470 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
13480 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
13490 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
134a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
134b0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
134c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
134d0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
134e0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
134f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13500 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
13510 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
13520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
13530 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
13540 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
13550 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
13560 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
13570 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
13580 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
13590 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
135a0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
135b0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
135c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
135d0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
135e0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
135f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13600 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
13610 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
13620 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
13630 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
13640 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
13650 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
13660 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13670 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13680 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13690 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
136a0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
136b0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
136c0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
136d0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
136e0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
136f0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13700 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
13710 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
13720 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
13730 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
13740 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
13750 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
13760 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13770 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13780 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13790 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
137a0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
137b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
137c0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
137d0 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
137e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
137f0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
13800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
13810 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
13820 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
13830 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
13840 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
13850 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
13860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
13870 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
13880 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
13890 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
138a0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
138b0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
138c0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
138d0 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
138e0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
138f0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
13900 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
13910 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
13920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13930 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
13940 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
13950 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
13960 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
13970 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
13980 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
13990 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
139a0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
139b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
139c0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
139d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
139e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
139f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13a00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
13a10 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
13a20 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
13a30 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
13a40 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13a50 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
13a60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13a70 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
13a80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
13a90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
13aa0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
13ab0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
13ac0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
13ad0 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
13ae0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13af0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
13b00 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
13b10 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
13b20 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
13b30 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
13b40 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
13b50 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
13b60 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13b70 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
13b80 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
13b90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
13ba0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
13bb0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
13bc0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13bd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13be0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13bf0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13c00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13c10 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13c20 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13c30 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13c40 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
13c50 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
13c60 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
13c70 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
13c80 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
13c90 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
13ca0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
13cb0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
13cc0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13cd0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13ce0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13cf0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13d00 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13d10 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13d20 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13d30 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13d40 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
13d50 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
13d60 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
13d70 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
13d80 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
13d90 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
13da0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
13db0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
13dc0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13dd0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13de0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13df0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13e00 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13e10 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13e20 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13e30 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13e40 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13e50 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13e60 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13e70 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
13e80 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
13e90 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
13ea0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
13eb0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
13ec0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13ed0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13ee0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13ef0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13f00 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
13f10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
13f20 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
13f30 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
13f40 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
13f50 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
13f60 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
13f70 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
13f80 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
13f90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
13fa0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
13fb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
13fc0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
13fd0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
13fe0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
13ff0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
14000 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
14010 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
14020 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
14030 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
14040 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
14050 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
14060 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
14070 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
14080 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
14090 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
140a0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
140b0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
140c0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
140d0 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
140e0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
140f0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
14100 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
14110 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
14120 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
14130 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
14140 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
14150 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
14160 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
14170 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
14180 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
14190 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
141a0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
141b0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
141c0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
141d0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
141e0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
141f0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
14200 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
14210 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
14220 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
14230 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
14240 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
14250 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
14260 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
14270 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
14280 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
14290 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
142a0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
142b0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
142c0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
142d0 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
142e0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
142f0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
14300 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
14310 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
14320 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
14330 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
14340 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
14350 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
14360 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
14370 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
14380 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14390 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
143a0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
143b0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
143c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
143d0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
143e0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
143f0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14400 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
14410 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
14420 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
14430 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
14440 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
14450 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
14460 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
14470 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
14480 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14490 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
144a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
144b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
144c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
144d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
144e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
144f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
14500 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
14510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14520 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
14530 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
14540 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
14550 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
14560 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14570 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
14580 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
14590 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
145a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
145b0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
145c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
145d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
145e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
145f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
14600 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
14610 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
14620 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
14630 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
14640 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
14650 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
14660 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
14670 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
14680 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
14690 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
146a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
146b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
146c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
146d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
146e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
146f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
14700 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
14710 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
14720 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
14730 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
14740 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14750 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
14760 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
14770 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
14780 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
14790 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
147a0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
147b0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
147c0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
147d0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
147e0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
147f0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
14800 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14810 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
14820 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
14830 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
14840 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
14850 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
14860 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14870 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
14880 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
14890 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
148a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
148b0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
148c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
148d0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
148e0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
148f0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14900 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14910 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
14920 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ries.**.** This 
14930 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
14940 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
14950 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
14960 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14970 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
14980 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
14990 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
149a0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
149b0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
149c0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
149d0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
149e0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
149f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
14a00 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
14a10 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
14a20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
14a30 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
14a40 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
14a50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
14a60 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
14a70 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
14a80 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
14a90 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
14aa0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
14ab0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
14ac0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
14ad0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
14ae0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
14af0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
14b00 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
14b10 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
14b20 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
14b30 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
14b40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
14b50 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
14b60 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
14b70 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
14b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14b90 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
14ba0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
14bb0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
14bc0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
14bd0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
14be0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
14bf0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
14c00 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
14c10 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
14c20 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
14c30 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
14c40 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
14c50 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
14c60 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
14c70 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
14c80 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
14c90 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
14ca0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
14cb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
14cc0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
14cd0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
14ce0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
14cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
14d00 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
14d10 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
14d20 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
14d30 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14d40 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
14d50 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
14d60 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
14d70 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
14d80 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
14d90 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
14da0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
14db0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
14dc0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14dd0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
14de0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14df0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
14e00 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
14e10 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
14e20 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
14e30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14e40 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
14e50 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14e60 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
14e70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14e80 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
14e90 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
14ea0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
14eb0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
14ec0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
14ed0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
14ee0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14ef0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
14f00 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
14f10 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
14f20 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
14f30 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
14f40 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
14f50 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
14f60 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
14f70 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
14f80 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
14f90 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
14fa0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
14fb0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
14fc0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14fd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14fe0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
14ff0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15000 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
15010 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
15020 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
15030 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
15040 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
15050 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
15060 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15070 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
15080 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15090 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
150a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
150b0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
150c0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
150d0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
150e0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
150f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
15100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
15110 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
15120 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
15130 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
15140 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
15150 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
15160 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
15170 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
15180 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
15190 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
151a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
151b0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
151c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
151d0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
151e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
151f0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
15200 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
15210 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
15220 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
15230 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
15240 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
15250 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
15260 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
15270 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
15280 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
15290 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
152a0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
152b0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
152c0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
152d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
152e0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
152f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
15300 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
15310 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
15320 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
15330 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15340 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
15350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
15360 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
15370 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
15380 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
15390 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
153a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
153b0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
153c0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
153d0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
153e0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
153f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
15400 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
15410 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
15420 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
15430 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
15440 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
15450 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
15460 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
15470 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
15480 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
15490 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
154a0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
154b0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
154c0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
154d0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
154e0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
154f0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
15500 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
15510 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
15520 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
15530 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
15540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
15550 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
15560 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15570 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15580 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15590 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
155a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
155b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
155c0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
155d0 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
155e0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
155f0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15600 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
15610 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
15620 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
15630 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
15640 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
15650 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
15660 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15670 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15680 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15690 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
156a0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
156b0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
156c0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
156d0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
156e0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
156f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15700 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
15710 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
15720 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
15730 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
15740 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
15750 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
15760 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15770 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15780 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
157a0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
157b0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
157c0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
157d0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
157e0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
157f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
15800 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
15810 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
15820 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
15830 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
15840 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
15850 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
15860 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
15870 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
15880 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
15890 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
158a0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
158b0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
158c0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
158d0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
158e0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
158f0 2a 2a 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f  ** ^(In sqlite3_
15900 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
15910 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
15920 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
15930 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
15940 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
15950 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
15960 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
15970 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
15980 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15990 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
159a0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
159b0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
159c0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
159d0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
159e0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
159f0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
15a00 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
15a10 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
15a20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
15a30 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
15a40 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
15a50 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
15a60 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
15a70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
15a80 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
15a90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15aa0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
15ab0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
15ac0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
15ad0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
15ae0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
15af0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
15b00 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
15b10 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
15b20 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
15b30 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
15b40 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
15b50 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
15b60 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
15b70 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
15b80 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
15b90 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
15ba0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
15bb0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
15bc0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
15bd0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
15be0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
15bf0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
15c00 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
15c10 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
15c20 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
15c30 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
15c40 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
15c50 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
15c60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
15c70 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
15c80 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
15c90 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
15ca0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
15cb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
15cc0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
15cd0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
15ce0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
15cf0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
15d00 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
15d10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
15d20 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
15d30 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
15d40 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
15d50 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
15d60 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
15d70 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
15d80 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
15d90 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
15da0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
15db0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
15dc0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
15dd0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
15de0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
15df0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
15e00 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
15e10 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
15e20 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
15e30 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
15e40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
15e50 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
15e60 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
15e70 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
15e80 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
15e90 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
15ea0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
15eb0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
15ec0 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20   literal.)^  By 
15ed0 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15ee0 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15ef0 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15f00 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15f10 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15f20 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15f30 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15f40 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15f50 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
15f60 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
15f70 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
15f80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
15f90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
15fa0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
15fb0 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
15fc0 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
15fd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15fe0 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
15ff0 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
16000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
16010 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16020 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16030 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
16040 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
16050 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
16060 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
16070 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
16080 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16090 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
160a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
160b0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
160c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
160d0 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
160e0 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
160f0 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
16100 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
16110 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
16120 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
16130 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
16140 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
16150 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16160 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16170 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16180 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
16190 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
161a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
161b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
161c0 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
161d0 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
161e0 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
161f0 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
16200 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
16210 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
16220 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16230 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
16240 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
16250 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
16260 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
16270 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16280 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
16290 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
162a0 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
162b0 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
162c0 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
162d0 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
162e0 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
162f0 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
16300 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
16310 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ral..**.** ^(The
16320 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
16330 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
16340 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
16350 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
16360 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
16370 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
16380 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
16390 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
163a0 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
163b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
163c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
163d0 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
163e0 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
163f0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
16400 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53  le quotes).)^  S
16410 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
16420 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
16430 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16440 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
16450 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
16460 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
16470 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
16480 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
16490 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
164a0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
164b0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
164c0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
164d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
164e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
164f0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
16500 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
16510 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
16520 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
16530 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
16540 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
16550 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  r..**.** ^(The "
16570 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
16580 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
16590 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
165a0 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
165b0 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
165c0 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
165d0 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
165e0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
165f0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
16600 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
16610 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
16620 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c  .)^.*/.char *sql
16630 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
16640 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63  st char*,...);.c
16650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
16660 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16670 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61  *, va_list);.cha
16680 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
16690 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
166a0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
166b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
166c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
166d0 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
166e0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
166f0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
16700 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
16710 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
16720 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
16730 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
16740 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
16750 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
16760 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
16770 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
16780 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
16790 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
167a0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
167b0 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
167c0 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
167d0 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
167e0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
167f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16800 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
16810 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
16820 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
16830 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
16840 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
16850 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
16860 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
16870 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
16880 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
16890 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
168a0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
168b0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
168c0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
168d0 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
168e0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
168f0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
16900 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
16910 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
16920 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
16930 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
16940 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
16950 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
16960 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
16970 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
16980 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
16990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
169a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
169b0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
169c0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
169d0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
169e0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
169f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
16a00 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
16a10 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
16a20 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
16a30 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
16a40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
16a50 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
16a60 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
16a70 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
16a80 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
16a90 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
16aa0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
16ab0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
16ac0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
16ad0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
16ae0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
16af0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
16b00 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
16b10 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
16b20 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
16b30 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
16b40 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
16b50 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
16b60 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
16b70 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
16b80 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
16b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
16ba0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
16bb0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
16bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
16bd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16be0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
16bf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16c00 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
16c10 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
16c20 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
16c30 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
16c40 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
16c50 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
16c60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
16c70 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
16c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
16c90 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
16ca0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
16cb0 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
16cc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16cd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16ce0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
16cf0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
16d00 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
16d10 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
16d20 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
16d30 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
16d40 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
16d50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
16d60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
16d70 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
16d80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
16d90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16da0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
16db0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
16dc0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
16dd0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
16de0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
16df0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
16e00 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
16e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
16e20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
16e30 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
16e40 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
16e50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
16e60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
16e70 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
16e80 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
16e90 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
16ea0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
16eb0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
16ec0 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
16ed0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
16ee0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
16ef0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
16f00 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
16f10 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
16f20 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
16f30 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
16f40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16f50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16f60 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
16f70 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
16f80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
16f90 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
16fa0 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
16fb0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
16fc0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
16fd0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
16fe0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
16ff0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
17000 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
17010 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
17020 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
17030 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
17040 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
17050 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
17060 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
17070 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
17080 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
17090 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
170a0 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
170b0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
170c0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
170d0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
170e0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
170f0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
17100 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
17110 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
17120 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
17130 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
17140 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
17150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
17160 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
17170 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
17180 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
17190 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
171a0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
171b0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
171c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
171d0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
171e0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
171f0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
17200 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
17210 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
17220 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
17230 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
17240 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
17250 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
17260 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
17270 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
17280 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
17290 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
172a0 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
172b0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
172c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
172d0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
172e0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
172f0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
17300 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
17310 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
17320 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
17330 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
17340 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
17350 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
17360 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
17370 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
17380 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
17390 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
173a0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
173b0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
173c0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
173d0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
173e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
173f0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17400 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
17410 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
17420 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
17430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
17440 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
17450 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
17460 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
17470 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
17480 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
17490 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
174a0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
174b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
174c0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
174d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
174e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
174f0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
17500 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
17510 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
17520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
17530 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
17540 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
17550 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
17560 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
17570 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
17580 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
17590 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
175a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
175b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
175c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
175d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
175e0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
175f0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
17600 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17610 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
17620 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
17630 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
17640 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
17650 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
17660 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
17670 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
17680 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
17690 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
176a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
176b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
176c0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
176d0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
176e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
176f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
17700 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
17710 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
17720 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
17730 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
17740 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
17750 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17760 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
17770 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
17780 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
17790 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
177a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
177b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
177c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
177d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
177e0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
177f0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
17800 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
17810 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
17820 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
17830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
17840 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
17850 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
17860 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
17870 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
17880 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
17890 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
178a0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
178b0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
178c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
178d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
178e0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
178f0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
17900 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
17910 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
17920 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
17930 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
17940 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
17950 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
17960 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
17970 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
17980 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
17990 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
179a0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
179b0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
179c0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
179d0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
179e0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
179f0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
17a00 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
17a10 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
17a20 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
17a30 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
17a40 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
17a50 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
17a60 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
17a70 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
17a80 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
17a90 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
17aa0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
17ab0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
17ac0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
17ad0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
17ae0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
17af0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
17b00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
17b10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
17b20 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
17b30 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
17b40 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
17b50 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
17b60 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
17b70 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
17b80 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
17b90 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
17ba0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
17bb0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
17bc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
17bd0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
17be0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
17bf0 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
17c00 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
17c10 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
17c20 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
17c30 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
17c40 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
17c50 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
17c60 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
17c70 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
17c80 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
17c90 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
17ca0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
17cb0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
17cc0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
17cd0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
17ce0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17cf0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
17d00 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76  .** method..*/.v
17d10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
17d20 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
17d30 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
17d40 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
17d50 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
17d60 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
17d70 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
17d80 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75  e registers a au
17d90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17da0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
17db0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
17dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
17dd0 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
17de0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
17df0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
17e00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17e10 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
17e20 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
17e30 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
17e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17e50 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
17e60 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
17e70 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
17e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
17e90 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
17ea0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
17eb0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
17ec0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
17ed0 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
17ee0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
17ef0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
17f00 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
17f10 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
17f20 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
17f30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
17f40 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
17f50 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
17f60 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
17f70 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
17f80 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
17f90 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
17fa0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
17fb0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
17fc0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
17fd0 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
17fe0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
17ff0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
18000 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
18010 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
18020 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
18030 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
18040 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
18050 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
18060 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
18070 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
18080 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18090 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
180a0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
180b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
180c0 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
180d0 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
180e0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
180f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
18100 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
18110 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
18120 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
18130 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
18140 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
18150 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
18160 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
18170 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
18180 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
18190 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
181a0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
181b0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
181c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
181d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
181e0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
181f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18200 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
18210 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
18220 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
18230 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
18240 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
18250 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
18260 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
18270 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
18280 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
18290 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
182a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
182b0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
182c0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
182d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
182e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
182f0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
18300 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
18310 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
18320 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
18330 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
18340 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
18350 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
18360 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
18370 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
18380 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
18390 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
183a0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
183b0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
183c0 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
183d0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
183e0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
183f0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
18400 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
18410 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
18420 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
18430 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
18440 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
18450 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
18460 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
18470 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
18480 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
18490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
184a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
184b0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
184c0 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
184d0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
184e0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
184f0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
18500 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
18510 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
18520 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
18530 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
18540 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
18550 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
18560 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
18570 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
18580 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
18590 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
185a0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
185b0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
185c0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
185d0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
185e0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
185f0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
18600 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
18610 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
18620 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
18630 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
18640 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
18650 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
18660 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
18670 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
18680 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
18690 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
186a0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
186b0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
186c0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
186d0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
186e0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
186f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
18700 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
18710 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
18720 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
18730 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
18740 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
18750 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
18760 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
18770 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
18780 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
18790 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
187a0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
187b0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
187c0 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
187d0 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
187e0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
187f0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
18800 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
18810 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
18820 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
18830 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
18840 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
18850 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
18860 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
18870 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
18880 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
18890 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
188a0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
188b0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
188c0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
188d0 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
188e0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
188f0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
18900 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
18910 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
18920 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
18930 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
18940 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
18950 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
18960 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
18970 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
18980 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
18990 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
189a0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
189b0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
189c0 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
189d0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
189e0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
189f0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
18a00 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
18a10 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
18a20 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
18a30 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
18a40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18a50 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
18a60 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
18a70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18a80 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
18a90 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
18aa0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
18ab0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
18ac0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
18ad0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
18ae0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
18af0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
18b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
18b10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18b20 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
18b30 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
18b40 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
18b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18b60 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
18b70 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
18b80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
18b90 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
18ba0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
18bb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
18bc0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
18bd0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
18be0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
18bf0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
18c00 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
18c10 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
18c20 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
18c30 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18c40 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
18c50 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
18c60 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
18c70 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
18c80 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
18c90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
18ca0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
18cb0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
18cc0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
18cd0 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
18ce0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
18cf0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
18d00 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
18d10 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
18d20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
18d30 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
18d40 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
18d50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18d60 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
18d70 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
18d80 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
18d90 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
18da0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
18db0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
18dc0 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
18dd0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
18de0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18df0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
18e00 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
18e10 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
18e20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
18e30 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
18e40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
18e50 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
18e60 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
18e70 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
18e80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
18e90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
18ea0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
18eb0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
18ec0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
18ed0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18ee0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
18ef0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
18f00 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
18f10 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
18f20 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
18f30 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
18f40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18f50 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18f60 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
18f70 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
18f80 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
18f90 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
18fa0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
18fb0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
18fc0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
18fd0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
18fe0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
18ff0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
19000 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
19010 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
19020 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
19030 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
19040 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
19050 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65  ormation..*/.#de
19060 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
19070 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
19080 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19090 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
190a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
190b0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
190c0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
190d0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
190e0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
190f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
19100 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
19110 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
19120 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
19130 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
19140 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
19150 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
19160 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
19170 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
19180 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
19190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
191a0 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
191b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
191c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
191d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
191e0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
191f0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
19200 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
19210 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
19220 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
19230 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
19240 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
19250 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
19260 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
19270 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
19280 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
19290 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
192a0 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
192b0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
192c0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
192d0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
192e0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
192f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
19300 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
19310 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
19320 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
19330 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
19340 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
19350 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19360 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
19370 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
19380 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
19390 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
193a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
193b0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
193c0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
193d0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
193e0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
193f0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
19400 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
19410 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
19420 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
19430 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
19440 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
19450 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
19460 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
19470 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
19480 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
19490 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
194a0 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
194b0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
194c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
194d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
194e0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
194f0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
19500 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
19510 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
19520 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
19530 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19540 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
19550 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19560 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
19570 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
19580 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19590 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
195a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
195b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
195c0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
195d0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
195e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
195f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19600 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
19610 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
19620 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19630 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19640 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19650 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
19660 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
19670 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
19680 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
196a0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
196b0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
196c0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
196d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
196e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
196f0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
19700 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
19710 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19720 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19740 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
19750 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
19760 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19770 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19790 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
197a0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
197b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
197c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
197d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
197e0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
197f0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
19800 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19810 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19820 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19830 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
19840 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
19850 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19860 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19870 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19880 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
19890 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
198a0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
198b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
198c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
198d0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
198e0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
198f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19900 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19910 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19920 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
19930 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
19940 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19950 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19960 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
19970 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
19980 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19990 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
199a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
199b0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
199c0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
199d0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
199e0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
199f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19a00 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
19a10 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
19a20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19a30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19a40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19a50 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
19a60 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
19a70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19a80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19a90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19aa0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
19ab0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
19ac0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
19ad0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
19ae0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
19af0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
19b00 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
19b10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19b20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
19b30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19b40 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
19b50 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
19b60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19b70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b90 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
19ba0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
19bb0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
19bc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19bd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19be0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
19bf0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
19c00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
19c10 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
19c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19c30 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
19c40 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
19c50 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
19c60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19c70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19c80 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
19c90 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
19ca0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
19cb0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19cc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
19cd0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
19ce0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
19cf0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
19d00 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
19d20 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
19d30 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
19d40 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19d50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
19d70 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
19d80 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
19d90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
19da0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19db0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19dc0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
19dd0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
19de0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
19df0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19e00 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
19e10 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
19e20 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
19e30 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
19e40 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19e50 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
19e60 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
19e70 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
19e80 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
19e90 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
19ea0 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
19eb0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
19ec0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
19ed0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
19ee0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
19ef0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
19f00 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
19f10 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
19f20 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
19f30 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
19f40 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
19f50 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
19f60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
19f70 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
19f80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
19f90 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
19fa0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
19fb0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
19fc0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
19fd0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
19fe0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19ff0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1a000 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1a010 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1a020 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1a030 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1a040 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1a050 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1a060 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1a070 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1a080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1a090 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1a0a0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1a0b0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1a0c0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1a0d0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1a0e0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1a0f0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1a100 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1a110 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1a120 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1a130 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1a140 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1a150 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1a160 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1a170 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1a180 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1a190 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1a1a0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1a1b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1a1c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1a1d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1a1e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1a1f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1a200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1a210 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1a220 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1a230 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1a240 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1a250 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1a260 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1a270 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1a280 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1a290 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1a2a0 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1a2b0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1a2c0 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1a2d0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1a2e0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1a2f0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1a300 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1a310 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1a320 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1a330 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1a340 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1a350 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1a360 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1a370 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1a380 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1a390 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1a3a0 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1a3b0 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1a3c0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1a3d0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1a3e0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1a3f0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1a400 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1a410 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1a420 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1a430 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1a440 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1a450 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1a460 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1a470 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1a480 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1a490 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1a4a0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1a4b0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1a4c0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1a4d0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1a4e0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1a4f0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1a500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a510 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1a520 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1a530 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1a540 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1a550 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1a560 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1a570 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1a580 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1a590 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1a5a0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1a5b0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1a5c0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a5d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1a5e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a5f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1a600 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1a610 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1a620 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1a630 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1a640 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1a650 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1a660 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1a670 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1a680 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1a690 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1a6a0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1a6b0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1a6c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1a6d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1a6e0 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
1a6f0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1a700 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1a710 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1a720 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1a730 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1a740 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1a750 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
1a760 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1a770 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1a780 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1a790 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1a7a0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1a7b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1a7c0 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1a7d0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1a7e0 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1a7f0 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1a800 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1a810 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1a820 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1a830 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1a840 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1a850 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1a860 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1a870 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1a880 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1a890 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1a8a0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a8b0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1a8c0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1a8d0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1a8e0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1a8f0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1a900 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1a910 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
1a920 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
1a930 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
1a940 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1a950 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1a960 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1a970 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1a980 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a990 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a9a0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1a9b0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1a9c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1a9d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1a9e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1a9f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1aa00 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1aa10 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1aa20 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1aa30 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1aa40 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
1aa50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1aa60 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1aa70 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1aa80 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1aa90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1aaa0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1aab0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1aac0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1aad0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1aae0 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1aaf0 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1ab00 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1ab10 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1ab20 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1ab30 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1ab40 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1ab50 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1ab60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ab70 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1ab80 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1ab90 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1aba0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1abb0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1abc0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1abd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1abe0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1abf0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1ac00 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1ac10 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1ac20 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1ac30 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1ac40 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1ac50 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1ac60 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1ac70 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1ac80 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1ac90 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1aca0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1acb0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1acc0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1acd0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1ace0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1acf0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1ad00 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1ad10 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1ad20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1ad30 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1ad40 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1ad50 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1ad60 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1ad70 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1ad80 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1ad90 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1ada0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1adb0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1adc0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1add0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1ade0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1adf0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1ae00 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1ae10 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1ae20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1ae30 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1ae40 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1ae50 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1ae60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1ae70 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1ae80 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1ae90 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1aea0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1aeb0 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1aec0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1aed0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1aee0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1aef0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1af00 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1af10 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1af20 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1af30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1af40 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1af50 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1af60 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1af70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1af80 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1af90 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1afa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1afb0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1afc0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1afd0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1afe0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1aff0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1b000 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1b010 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1b020 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1b030 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1b040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b050 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1b060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1b070 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b080 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1b090 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1b0a0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1b0b0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1b0c0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1b0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1b0e0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1b0f0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1b100 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1b110 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1b120 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
1b130 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1b140 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  E] flags:)^.**.*
1b150 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1b160 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1b170 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1b180 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1b190 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1b1a0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1b1b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1b1c0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1b1d0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1b1e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1b1f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b200 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1b210 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
1b220 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1b230 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1b240 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1b250 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1b260 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
1b270 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
1b280 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1b290 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1b2a0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
1b2b0 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
1b2c0 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
1b2d0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
1b2e0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
1b2f0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1b300 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1b310 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1b320 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
1b330 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1b340 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1b350 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b360 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1b370 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
1b380 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69 74  nd is creates it
1b390 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1b3a0 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1b3b0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1b3c0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1b3d0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1b3e0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1b3f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b400 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1b410 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1b420 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1b430 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1b440 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1b450 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1b460 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1b470 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74  bove or one of t
1b480 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  he combinations 
1b490 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62  shown above comb
1b4a0 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ined.** with the
1b4b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b4c0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1b4d0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1b4e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1b4f0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e  _SHAREDCACHE] an
1b500 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1b510 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1b520 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
1b530 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1b540 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1b550 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1b560 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1b570 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1b580 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b590 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1b5a0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1b5b0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1b5c0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1b5d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1b5e0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1b5f0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1b600 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1b610 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1b620 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1b630 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1b640 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1b650 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b660 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1b670 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1b680 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1b690 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1b6a0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1b6b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1b6c0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1b6d0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1b6e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1b6f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1b700 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1b710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b720 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1b730 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1b740 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1b750 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1b760 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1b770 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1b780 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1b790 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1b7a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1b7b0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1b7c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1b7d0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1b7e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1b7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1b800 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1b810 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1b820 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1b830 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1b840 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b850 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1b860 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1b870 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1b880 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1b890 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1b8a0 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1b8b0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
1b8c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b8d0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1b8e0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1b8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1b900 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1b910 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1b920 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1b930 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1b940 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1b950 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1b960 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1b970 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1b980 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1b990 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1b9a0 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1b9b0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1b9c0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1b9d0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1b9e0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1b9f0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1ba00 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1ba10 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1ba20 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1ba30 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1ba40 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1ba50 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1ba60 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1ba70 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1ba80 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1ba90 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1baa0 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1bab0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1bac0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1bad0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1bae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1baf0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1bb00 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1bb10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1bb20 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1bb30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1bb40 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1bb50 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1bb60 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1bb70 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1bb80 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1bb90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1bba0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1bbb0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1bbc0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1bbd0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1bbe0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1bbf0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1bc00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1bc10 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1bc20 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1bc30 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1bc40 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1bc50 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1bc60 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1bc70 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1bc80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1bc90 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1bca0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1bcb0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1bcc0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1bcd0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1bce0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1bcf0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1bd00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1bd10 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1bd20 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1bd30 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1bd40 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1bd50 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
1bd60 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1bd70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1bd80 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1bd90 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1bda0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1bdb0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1bdc0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1bdd0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1bde0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1bdf0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1be00 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1be10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1be20 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1be30 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1be40 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1be50 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1be60 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1be70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1be80 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1be90 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1bea0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1beb0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1bec0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1bed0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1bee0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1bef0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1bf00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1bf10 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1bf20 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1bf30 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1bf40 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1bf50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bf60 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1bf70 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1bf80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1bf90 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1bfa0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1bfb0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1bfc0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1bfd0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1bfe0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1bff0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1c000 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1c010 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1c020 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1c030 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1c040 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1c050 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1c060 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1c070 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1c080 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1c090 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1c0a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1c0b0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1c0c0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1c0d0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1c0e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1c0f0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1c100 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1c110 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1c120 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1c130 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1c140 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1c150 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1c160 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1c170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1c180 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1c190 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1c1a0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1c1b0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1c1c0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1c1d0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c1e0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1c1f0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1c200 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c210 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1c220 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1c230 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1c240 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1c250 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1c260 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1c270 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1c280 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1c290 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1c2a0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1c2b0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1c2c0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1c2d0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1c2e0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1c2f0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1c300 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1c310 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1c320 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1c330 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1c340 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1c350 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1c360 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1c370 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1c380 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1c390 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1c3a0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1c3b0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1c3c0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1c3d0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1c3e0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1c3f0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1c400 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1c410 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1c420 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1c430 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1c440 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1c450 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1c460 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1c470 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1c480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c490 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1c4a0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1c4b0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1c4c0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1c4d0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1c4e0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1c4f0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1c500 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1c510 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1c520 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1c530 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1c540 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1c550 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1c560 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1c570 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1c580 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1c590 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1c5a0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1c5b0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1c5c0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1c5d0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1c5e0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1c5f0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1c600 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1c610 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1c620 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1c630 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1c640 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1c650 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1c660 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1c670 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1c680 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1c690 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1c6a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1c6b0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1c6c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1c6d0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1c6e0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1c6f0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1c700 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1c710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1c720 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1c730 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1c740 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1c750 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1c760 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1c770 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1c780 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1c790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c7a0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1c7b0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1c7c0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1c7d0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1c7e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1c7f0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1c800 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1c810 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1c820 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1c830 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1c840 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1c850 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c860 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1c870 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1c880 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1c890 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1c8a0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1c8b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1c8c0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1c8d0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1c8e0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1c8f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c900 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1c910 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1c920 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1c930 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1c940 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1c950 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1c960 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1c970 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1c980 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1c990 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1c9a0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1c9b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1c9c0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1c9d0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1c9e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1c9f0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1ca00 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1ca10 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1ca20 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1ca30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1ca40 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1ca50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ca60 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1ca70 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1ca80 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1ca90 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1caa0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1cab0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1cac0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1cad0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1cae0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1caf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1cb00 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1cb10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1cb20 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1cb30 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1cb40 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1cb50 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1cb60 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1cb70 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1cb80 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1cb90 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1cba0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1cbb0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1cbc0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1cbd0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1cbe0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
1cbf0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
1cc00 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1cc10 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1cc20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1cc30 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
1cc40 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
1cc50 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
1cc60 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
1cc70 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
1cc80 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
1cc90 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
1cca0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1ccb0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
1ccc0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
1ccd0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
1cce0 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
1ccf0 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
1cd00 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
1cd10 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
1cd20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
1cd30 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
1cd40 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
1cd50 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
1cd60 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
1cd70 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
1cd80 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
1cd90 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
1cda0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
1cdb0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1cdc0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1cdd0 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
1cde0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1cdf0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
1ce00 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
1ce10 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
1ce20 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
1ce30 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
1ce40 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
1ce50 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
1ce60 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
1ce70 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
1ce80 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
1ce90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1cea0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
1ceb0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
1cec0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1ced0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1cee0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1cef0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1cf00 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1cf10 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1cf20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1cf30 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1cf40 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1cf50 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1cf60 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1cf70 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1cf80 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
1cf90 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1cfa0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1cfb0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1cfc0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1cfd0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1cfe0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1cff0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1d000 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1d010 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1d020 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1d030 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1d040 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1d050 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1d060 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1d070 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1d080 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1d090 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1d0a0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1d0b0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1d0c0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1d0d0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1d0e0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1d0f0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1d100 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1d110 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d120 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1d130 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1d140 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1d150 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1d160 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1d170 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1d180 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1d190 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1d1a0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1d1b0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1d1c0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1d1d0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1d1e0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1d1f0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1d200 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
1d210 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1d220 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1d230 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1d240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d250 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1d260 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
1d270 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1d280 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
1d290 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1d2a0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1d2b0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1d2c0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
1d2d0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
1d2e0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
1d2f0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
1d300 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1d310 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
1d320 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
1d330 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1d340 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
1d350 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
1d360 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1d370 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
1d380 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
1d390 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
1d3a0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1d3b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d3c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1d3d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
1d3e0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
1d3f0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
1d400 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
1d410 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  .<dd>)^.**.** ^(
1d420 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d430 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1d440 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d450 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1d460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d470 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
1d480 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d490 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1d4a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d4b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d4c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
1d4d0 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
1d4e0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
1d4f0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1d500 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
1d510 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d520 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1d530 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1d540 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1d550 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1d560 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d570 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1d580 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1d590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d5a0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
1d5b0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
1d5c0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
1d5d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d5e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1d5f0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
1d600 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d610 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
1d620 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
1d630 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
1d640 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
1d650 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d660 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
1d670 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d680 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
1d690 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
1d6a0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
1d6b0 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
1d6c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
1d6d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
1d6e0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
1d6f0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
1d700 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
1d710 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
1d720 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
1d730 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
1d740 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
1d750 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d760 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1d770 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1d780 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1d790 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1d7a0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1d7b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1d7c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d7d0 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1d7e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d7f0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1d800 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1d810 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
1d820 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d830 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1d840 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1d850 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d860 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1d870 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1d880 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
1d890 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
1d8a0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
1d8b0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1d8c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1d8d0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1d8e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d8f0 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
1d900 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
1d910 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
1d920 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
1d930 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1d940 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1d950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d960 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1d970 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1d980 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1d990 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1d9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d9b0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1d9c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1d9d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d9e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1d9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1da00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1da10 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1da20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1da30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1da40 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1da50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1da60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1da70 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1da80 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1da90 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1daa0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1dab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dac0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1dad0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1dae0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1daf0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1db00 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1db10 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1db20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1db30 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1db40 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1db50 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1db60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1db70 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1db80 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1db90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1dba0 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1dbb0 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1dbc0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1dbd0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1dbe0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1dbf0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1dc00 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1dc10 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1dc20 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1dc30 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1dc40 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1dc50 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1dc60 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1dc70 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1dc80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1dc90 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1dca0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dcb0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1dcc0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1dcd0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1dce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1dcf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1dd00 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1dd10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1dd20 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1dd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1dd40 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1dd50 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1dd60 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1dd70 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1dd80 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1dd90 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1dda0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1ddb0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1ddc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1ddd0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1dde0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1ddf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1de00 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1de10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1de20 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1de30 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1de40 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1de50 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1de60 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1de70 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1de80 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1de90 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1dea0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1deb0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1dec0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1ded0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1dee0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1def0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1df00 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1df10 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1df20 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1df30 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1df40 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1df50 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1df60 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1df70 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1df80 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1df90 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1dfa0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1dfb0 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1dfc0 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1dfd0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1dfe0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1dff0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1e000 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1e010 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1e020 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1e030 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1e040 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1e050 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1e060 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1e070 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1e080 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1e090 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1e0a0 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1e0b0 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1e0c0 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1e0d0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1e0e0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1e0f0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1e100 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1e110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1e120 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1e130 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1e140 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1e150 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1e160 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1e170 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1e180 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1e190 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1e1a0 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1e1b0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1e1c0 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1e1d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e1e0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1e1f0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1e200 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e210 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1e220 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1e230 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1e240 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1e250 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1e260 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1e270 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1e280 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1e290 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1e2a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1e2b0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1e2c0 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1e2d0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1e2e0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1e2f0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1e300 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1e310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1e320 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1e330 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1e340 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1e350 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1e360 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1e370 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1e380 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1e390 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1e3a0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1e3b0 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1e3c0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1e3d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1e3f0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1e400 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e410 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1e420 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1e430 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1e440 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1e450 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1e460 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1e470 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1e480 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1e490 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1e4a0 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1e4b0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1e4c0 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1e4d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1e4e0 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1e4f0 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1e500 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1e510 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1e520 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1e530 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1e540 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1e550 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1e560 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1e570 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1e580 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1e590 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1e5a0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1e5b0 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1e5c0 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1e5d0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1e5e0 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1e5f0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1e600 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1e610 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1e620 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1e630 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1e640 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1e650 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1e660 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  n..** </li>.**.*
1e670 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20  * <li>.** ^When 
1e680 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c  an error occurs,
1e690 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e6a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e  ] will return on
1e6b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65  e of the detaile
1e6c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  d.** [error code
1e6d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  s] or [extended 
1e6e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e  error codes].  ^
1e6f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1e700 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
1e710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e720 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1e730 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
1e740 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1e750 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74  lt code.** and t
1e760 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
1e770 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b  ould have to mak
1e780 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20  e a second call 
1e790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
1e7a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  t()].** in order
1e7b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64   to find the und
1e7c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66  erlying cause of
1e7d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69   the problem. Wi
1e7e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70  th the "v2" prep
1e7f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  are.** interface
1e800 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  s, the underlyin
1e810 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65  g reason for the
1e820 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e830 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ed immediately..
1e840 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1e850 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  li>.** ^If the s
1e860 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f  pecific value bo
1e870 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  und to [paramete
1e880 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1e890 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57  er] in the .** W
1e8a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
1e8b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
1e8c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20  choice of query 
1e8d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65  plan for a state
1e8e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ment,.** then th
1e8f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c  e statement will
1e900 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
1e910 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73  y recompiled, as
1e920 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1e930 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20  en .** a schema 
1e940 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66  change, on the f
1e950 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73  irst  [sqlite3_s
1e960 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1e970 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1e980 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
1e990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e9a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61  bindings] of tha
1e9b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  t [parameter]. .
1e9c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63  ** ^The specific
1e9d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d   value of WHERE-
1e9e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65  clause [paramete
1e9f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  r] might influen
1ea00 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63  ce the .** choic
1ea10 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
1ea20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1ea30 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e   is the left-han
1ea40 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b  d side of a [LIK
1ea50 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20  E].** or [GLOB] 
1ea60 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74  operator or if t
1ea70 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
1ea80 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69  compared to an i
1ea90 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  ndexed column.**
1eaa0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45   and the [SQLITE
1eab0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63  _ENABLE_STAT2] c
1eac0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1ead0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
1eae0 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a  * the .** </li>.
1eaf0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
1eb00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1eb10 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1eb20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1eb30 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1eb40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1eb50 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1eb60 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1eb70 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
1eb80 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1eb90 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1eba0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ebb0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1ebc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1ebd0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1ebe0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1ebf0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ec00 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
1ec10 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1ec20 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1ec30 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1ec40 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1ec50 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
1ec60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1ec70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1ec80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1ec90 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1eca0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1ecb0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1ecc0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1ecd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1ece0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1ecf0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1ed00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1ed10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1ed20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1ed30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ed40 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1ed50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1ed60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1ed70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1ed80 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ed90 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1eda0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1edb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1edc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1edd0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1ede0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1edf0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1ee00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1ee10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1ee20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1ee30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ee40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1ee50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1ee60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1ee70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ee80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1ee90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1eea0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1eeb0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1eec0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1eed0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1eee0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
1eef0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1ef00 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1ef10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1ef20 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1ef30 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1ef40 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1ef50 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1ef60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1ef70 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1ef80 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1ef90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1efa0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1efb0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1efc0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1efd0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1efe0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1eff0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1f000 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1f010 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1f020 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
1f030 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
1f040 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
1f050 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
1f060 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
1f070 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
1f080 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
1f090 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
1f0a0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
1f0b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
1f0c0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
1f0d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
1f0e0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1f0f0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
1f110 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
1f120 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1f130 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
1f140 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
1f150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f160 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1f170 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
1f180 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
1f190 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
1f1a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
1f1b0 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
1f1c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
1f1d0 6e 2d 7a 65 72 6f 29 20 69 66 20 0a 2a 2a 20 61  n-zero) if .** a
1f1e0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
1f1f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f200 6e 74 5d 20 58 20 69 73 20 6d 61 6b 65 73 20 6e  nt] X is makes n
1f210 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
1f220 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
1f230 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
1f240 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
1f250 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
1f260 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1f270 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
1f280 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
1f290 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
1f2a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
1f2b0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
1f2c0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
1f2d0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
1f2e0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
1f2f0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
1f300 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
1f310 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
1f320 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
1f330 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
1f340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1f350 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
1f360 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1f370 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
1f380 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
1f390 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f3a0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
1f3b0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
1f3c0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
1f3d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f3e0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
1f3f0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
1f400 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
1f410 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1f420 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
1f430 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
1f440 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
1f450 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
1f460 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
1f470 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
1f480 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
1f490 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
1f4a0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
1f4b0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
1f4c0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
1f4d0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
1f4e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
1f4f0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
1f500 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
1f510 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
1f520 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
1f530 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
1f540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
1f550 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
1f560 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
1f570 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
1f580 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
1f590 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
1f5a0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
1f5b0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
1f5c0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
1f5d0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
1f5e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
1f5f0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
1f600 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
1f610 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
1f620 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
1f630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
1f640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f650 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
1f660 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
1f670 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
1f680 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
1f690 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
1f6a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f6b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
1f6c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1f6d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f6e0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1f6f0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1f700 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1f710 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1f720 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1f730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1f740 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1f750 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1f760 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1f770 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1f780 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1f790 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1f7a0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1f7b0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1f7c0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1f7d0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1f7e0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
1f7f0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1f800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1f810 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1f820 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1f830 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1f840 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1f850 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1f860 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1f870 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1f880 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1f890 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1f8a0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1f8b0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1f8c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1f8d0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1f8e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1f8f0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1f900 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1f910 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1f920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1f930 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1f940 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1f950 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1f960 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1f970 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1f980 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1f990 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1f9a0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1f9b0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1f9c0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1f9d0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1f9e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1f9f0 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1fa00 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1fa10 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1fa20 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1fa30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fa40 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1fa50 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1fa60 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1fa70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fa80 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1fa90 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1faa0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1fab0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1fac0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fad0 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1fae0 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1faf0 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1fb00 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1fb10 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1fb20 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1fb30 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1fb40 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1fb50 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1fb60 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1fb70 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1fb80 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1fb90 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1fba0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1fbb0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1fbc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1fbd0 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1fbe0 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1fbf0 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1fc00 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1fc10 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1fc20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1fc30 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1fc40 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1fc50 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1fc60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1fc70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1fc80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1fc90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1fca0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
1fcb0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
1fcc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fcd0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1fce0 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1fcf0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1fd00 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1fd10 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
1fd20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1fd30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
1fd40 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1fd50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
1fd60 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
1fd70 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1fd80 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1fd90 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
1fda0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
1fdb0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1fdc0 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
1fdd0 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
1fde0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1fdf0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
1fe00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1fe10 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
1fe20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
1fe30 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
1fe40 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
1fe50 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
1fe60 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
1fe70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1fe80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
1fe90 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
1fea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
1feb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fec0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
1fed0 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
1fee0 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1fef0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1ff00 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1ff10 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1ff20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1ff30 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
1ff40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1ff50 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
1ff60 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
1ff70 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ff80 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
1ff90 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1ffa0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
1ffb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ffc0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ffd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1ffe0 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1fff0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
20000 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
20010 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
20020 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
20030 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
20040 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
20050 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
20060 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
20070 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
20080 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
20090 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
200a0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
200b0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
200c0 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
200d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
200e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
200f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
20100 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
20110 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
20120 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
20130 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
20140 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
20150 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
20160 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
20170 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
20180 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
20190 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
201a0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
201b0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
201c0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
201d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
201e0 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
201f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20200 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
20210 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
20220 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
20230 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
20240 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
20250 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
20260 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
20270 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
20280 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
20290 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
202a0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
202b0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
202c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
202d0 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
202e0 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
202f0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
20300 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
20310 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
20320 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
20330 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
20340 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
20350 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
20360 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
20370 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
20380 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
20390 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
203a0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
203b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
203c0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
203d0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
203e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
203f0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
20400 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20410 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
20420 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
20430 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
20440 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
20450 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
20460 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20470 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
20480 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
20490 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
204a0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
204b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
204c0 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
204d0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
204e0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
204f0 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
20500 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
20510 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
20520 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
20530 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
20540 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
20550 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
20560 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
20570 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
20580 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
20590 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
205a0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
205b0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
205c0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
205d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
205e0 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
205f0 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
20600 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
20610 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
20620 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
20630 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
20640 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
20650 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
20660 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
20670 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
20680 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
20690 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
206a0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
206b0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
206c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
206d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
206e0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
206f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ameter..**.** ^(
20700 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
20710 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
20720 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
20730 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
20740 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
20750 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
20760 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
20770 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
20780 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
20790 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
207a0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
207b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
207c0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
207d0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
207e0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
207f0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
20800 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
20810 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
20820 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
20830 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
20840 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
20850 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
20860 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
20870 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
20880 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
20890 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
208a0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
208b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
208c0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
208d0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
208e0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
208f0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
20900 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
20910 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
20920 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
20930 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
20940 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
20950 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
20960 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
20970 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
20980 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
20990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
209a0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
209b0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
209c0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
209d0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
209e0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
209f0 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
20a00 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
20a10 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
20a20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
20a30 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
20a40 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
20a50 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
20a60 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
20a70 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
20a80 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
20a90 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
20aa0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
20ab0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
20ac0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
20ad0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
20ae0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
20af0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
20b00 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
20b10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
20b20 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
20b30 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
20b40 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
20b50 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
20b60 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
20b70 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
20b80 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
20b90 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
20ba0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
20bb0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
20bc0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
20bd0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
20be0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
20bf0 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
20c00 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
20c10 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
20c20 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
20c30 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
20c40 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
20c50 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
20c60 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
20c70 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
20c80 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
20c90 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
20ca0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
20cb0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
20cc0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
20cd0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
20ce0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
20cf0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
20d00 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
20d10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
20d20 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
20d30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
20d40 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
20d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
20d60 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
20d70 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
20d80 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
20d90 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
20da0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
20db0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
20dc0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
20dd0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
20de0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
20df0 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
20e00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
20e10 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
20e20 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
20e30 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
20e40 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
20e50 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
20e60 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
20e70 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
20e80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
20e90 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
20ea0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
20eb0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
20ec0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
20ed0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
20ee0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20ef0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
20f00 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
20f10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
20f20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
20f30 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
20f40 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
20f50 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
20f60 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
20f70 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
20f80 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
20f90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
20fa0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
20fb0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
20fc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
20fd0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
20fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20ff0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21000 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
21010 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21020 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
21030 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
21040 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
21050 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
21060 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
21070 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
21080 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
21090 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
210a0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
210b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
210c0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
210d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
210e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
210f0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
21100 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
21110 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
21120 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
21130 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
21140 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
21150 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
21160 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21170 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
21180 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
21190 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
211a0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
211b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
211c0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
211d0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
211e0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
211f0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
21200 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
21210 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
21220 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
21230 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
21240 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21250 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
21260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
21270 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
21280 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
21290 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
212a0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
212b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
212c0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
212d0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
212e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
212f0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
21300 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
21310 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
21320 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
21330 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
21340 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
21350 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
21360 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
21370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21380 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
21390 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
213a0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
213b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
213c0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
213d0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
213e0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
213f0 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
21400 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
21410 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
21420 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
21430 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
21440 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
21450 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
21460 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
21470 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
21480 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
21490 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
214a0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
214b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
214c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
214d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
214e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
214f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21500 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
21510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21520 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21530 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
21540 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
21550 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
21560 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
21570 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
21580 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
21590 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
215a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
215b0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
215c0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
215d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
215e0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
215f0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
21600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21610 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
21620 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
21630 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
21640 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
21650 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
21660 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
21670 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
21680 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
21690 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
216a0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
216b0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
216c0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
216d0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
216e0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
216f0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
21700 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
21710 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
21720 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
21730 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
21740 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
21750 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
21760 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
21770 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
21780 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
21790 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
217a0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
217b0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
217c0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
217d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
217e0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
217f0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
21800 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
21810 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
21820 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
21830 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
21840 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
21850 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
21860 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
21870 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
21880 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
21890 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
218a0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
218b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
218c0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
218d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
218e0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
218f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21900 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21910 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
21920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21930 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
21940 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21950 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21960 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
21970 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21980 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
21990 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
219a0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
219b0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
219c0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
219d0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
219e0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
219f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
21a00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
21a10 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
21a20 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
21a30 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
21a40 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
21a50 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
21a60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
21a70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21a80 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
21a90 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
21aa0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
21ab0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
21ac0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
21ad0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
21ae0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
21af0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
21b00 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
21b10 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
21b20 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
21b30 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
21b40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21b50 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
21b60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
21b70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
21b80 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
21b90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21ba0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
21bb0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
21bc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21bd0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
21be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21bf0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21c00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21c10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
21c20 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
21c30 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
21c40 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
21c50 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
21c60 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
21c70 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
21c80 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
21c90 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
21ca0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
21cb0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21cc0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
21cd0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
21ce0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
21cf0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
21d00 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
21d10 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
21d20 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
21d30 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
21d40 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
21d50 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
21d60 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
21d70 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
21d80 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
21d90 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
21da0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
21db0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
21dc0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
21dd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21de0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
21df0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
21e00 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
21e10 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
21e20 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
21e30 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
21e40 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
21e50 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
21e60 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
21e70 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
21e80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
21e90 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
21ea0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
21eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
21ec0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
21ed0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
21ee0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
21ef0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
21f00 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
21f10 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
21f20 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
21f30 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
21f40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
21f50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
21f60 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
21f70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
21f80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
21f90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
21fa0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
21fb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
21fc0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
21fd0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
21fe0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
21ff0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
22000 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
22010 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
22020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22030 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
22040 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
22050 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
22060 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
22070 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
22080 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
22090 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
220a0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
220b0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
220c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
220d0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
220e0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
220f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22100 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
22110 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
22120 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22130 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
22140 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
22150 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
22160 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
22170 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
22180 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
22190 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
221a0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
221b0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
221c0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
221d0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
221e0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
221f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
22200 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
22210 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
22220 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
22230 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
22240 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
22250 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
22260 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
22270 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
22280 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
22290 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
222a0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
222b0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
222c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
222d0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
222e0 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
222f0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
22300 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
22310 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
22320 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
22330 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22340 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
22350 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
22360 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22380 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
22390 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
223a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
223b0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
223c0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
223d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
223e0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
223f0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
22400 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
22410 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
22420 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
22430 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
22440 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
22450 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
22460 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
22470 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
22480 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
22490 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
224a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
224b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
224c0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
224d0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
224e0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
224f0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
22500 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
22510 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
22520 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22530 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
22540 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
22550 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
22560 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
22570 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
22580 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
22590 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
225a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
225b0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
225c0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
225d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
225e0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
225f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
22600 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
22610 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
22620 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
22630 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
22640 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
22650 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
22660 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
22670 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
22680 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
22690 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
226a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
226b0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
226c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
226d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
226e0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
226f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
22700 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
22710 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
22720 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
22730 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
22740 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
22750 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
22760 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
22770 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
22780 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
22790 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
227a0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
227b0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
227c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
227d0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
227e0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
227f0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
22800 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
22810 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
22820 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
22830 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
22840 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
22850 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
22860 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
22870 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
22880 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
22890 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
228a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
228b0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
228c0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
228d0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
228e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
228f0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
22900 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
22910 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
22920 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
22930 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
22940 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
22950 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
22960 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
22970 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
22980 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
22990 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
229a0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
229b0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
229c0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
229d0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
229e0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
229f0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
22a00 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
22a10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
22a20 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
22a30 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
22a40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
22a50 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
22a60 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
22a70 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
22a80 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
22a90 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
22aa0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
22ab0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
22ac0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
22ad0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
22ae0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
22af0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
22b00 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
22b10 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
22b20 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
22b30 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
22b40 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
22b50 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
22b60 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
22b70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
22b80 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
22b90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
22bb0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
22bc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
22bd0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22be0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
22bf0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
22c00 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
22c10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22c20 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
22c30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
22c40 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
22c50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
22c60 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
22c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
22c80 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
22c90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
22ca0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
22cb0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
22cc0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
22cd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
22ce0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
22cf0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
22d00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
22d10 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
22d20 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
22d30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
22d40 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
22d50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
22d60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
22d70 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
22d80 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
22d90 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
22da0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
22db0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
22dc0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
22dd0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
22de0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
22df0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
22e00 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
22e10 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
22e20 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
22e30 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
22e40 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
22e50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
22e60 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
22e70 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
22e80 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
22e90 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
22ea0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
22eb0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
22ec0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
22ed0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
22ee0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
22ef0 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
22f00 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
22f10 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
22f20 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
22f30 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
22f40 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
22f50 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
22f60 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
22f70 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
22f80 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
22f90 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
22fa0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
22fb0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
22fc0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
22fd0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
22fe0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
22ff0 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
23000 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
23010 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
23020 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
23030 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
23040 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
23050 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
23060 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
23070 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
23080 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
23090 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
230a0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
230b0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
230c0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
230d0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
230e0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
230f0 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
23100 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
23110 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
23120 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
23130 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23140 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
23150 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
23160 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
23170 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
23180 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
23190 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
231a0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
231b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
231c0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
231d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
231e0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
231f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
23200 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
23210 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
23220 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
23230 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
23240 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
23250 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
23260 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
23270 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
23280 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
23290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
232a0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
232b0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
232c0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
232d0 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
232e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
232f0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
23300 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
23310 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
23320 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
23330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
23340 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
23350 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
23360 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
23370 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
23380 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
23390 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
233a0 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
233b0 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
233c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
233d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
233e0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
233f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23400 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
23410 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
23420 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
23430 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
23440 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23450 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
23460 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
23470 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
23480 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
23490 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
234a0 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
234b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
234c0 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
234d0 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
234e0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
234f0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
23500 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
23510 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
23520 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
23530 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
23540 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
23550 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
23560 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
23570 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
23580 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
23590 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
235a0 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
235b0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
235c0 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
235d0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
235e0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
235f0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
23600 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
23610 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
23620 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
23630 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
23640 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
23650 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
23660 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
23670 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
23680 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
23690 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
236a0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
236b0 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
236c0 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
236d0 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
236e0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
236f0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
23700 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
23710 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
23720 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
23730 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
23740 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
23750 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
23760 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
23770 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
23780 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
23790 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
237a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
237b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
237c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
237d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
237e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
237f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
23800 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
23810 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
23820 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
23830 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
23840 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
23850 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
23860 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23870 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
23880 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
23890 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
238a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
238b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
238c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
238d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
238e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
238f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
23900 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
23910 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
23920 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
23930 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
23940 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
23950 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
23960 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
23970 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
23980 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
23990 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
239a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
239b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
239c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
239d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
239e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
239f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
23a00 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
23a10 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
23a20 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
23a30 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
23a40 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
23a50 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
23a60 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
23a70 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
23a80 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
23a90 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
23aa0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
23ab0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
23ac0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
23ad0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
23ae0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
23af0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
23b00 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
23b10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
23b20 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
23b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23b40 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
23b50 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
23b60 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
23b70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
23b80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
23b90 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
23ba0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
23bb0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
23bc0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
23bd0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
23be0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
23bf0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
23c00 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
23c10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23c20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
23c30 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
23c40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23c50 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
23c60 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
23c70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
23c80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
23c90 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
23ca0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
23cb0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
23cc0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
23cd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
23ce0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
23cf0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
23d00 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
23d10 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
23d20 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
23d30 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
23d40 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
23d50 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
23d60 33 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73  3.6.23.1, it was
23d70 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74   required.** aft
23d80 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
23d90 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
23da0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
23db0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74  SQLITE_ROW] that
23dc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
23dd0 65 74 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20  et()] be called 
23de0 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
23df0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
23e00 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
23e10 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
23e20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  to invoke [sqlit
23e30 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74  e3_reset()] in t
23e40 68 69 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a  his way would.**
23e50 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
23e60 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
23e70 74 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65  turn from sqlite
23e80 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
23e90 66 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  fter.** version 
23ea0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
23eb0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 20 63  3_step() began c
23ec0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
23ed0 72 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74  reset()] .** aut
23ee0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
23ef0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
23f00 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
23f10 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
23f20 53 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  SUSE].  .**.** <
23f30 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
23f40 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
23f50 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
23f60 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
23f70 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
23f80 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
23f90 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
23fa0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
23fb0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
23fc0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
23fd0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
23fe0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
23ff0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
24000 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
24010 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
24020 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24030 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
24040 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
24050 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
24060 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
24070 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
24080 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
24090 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
240a0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
240b0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
240c0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
240d0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
240e0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
240f0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
24100 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
24110 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
24120 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
24130 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24140 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24150 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
24160 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
24170 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
24180 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
24190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
241a0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
241b0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
241c0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
241d0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
241e0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
241f0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
24200 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
24210 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
24220 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
24230 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24240 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
24250 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
24260 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
24270 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
24280 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
24290 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
242a0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
242b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
242c0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
242d0 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
242e0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
242f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
24300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24310 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
24320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
24330 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
24340 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
24350 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
24360 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
24370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
24380 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
24390 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
243a0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
243b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
243c0 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
243d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
243e0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
243f0 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
24400 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
24410 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
24420 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
24440 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
24450 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
24460 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
24470 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24480 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
24490 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
244a0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
244b0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
244c0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
244d0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
244e0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
244f0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
24500 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
24510 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24520 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
24530 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
24540 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
24550 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
24560 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
24570 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
24580 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24590 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
245a0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
245b0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
245c0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
245d0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
245e0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
245f0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
24600 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
24610 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
24620 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
24630 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
24640 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
24650 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
24660 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
24670 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
24680 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
24690 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
246a0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
246b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
246c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
246d0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
246e0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
246f0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
24700 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
24710 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
24720 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
24730 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
24740 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
24750 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
24760 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
24770 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
24780 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
24790 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
247a0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
247b0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
247c0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
247d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
247e0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
247f0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
24800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
24810 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
24820 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
24830 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
24840 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
24850 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
24860 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
24870 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
24880 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
24890 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
248a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
248b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
248c0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
248d0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
248e0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
248f0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
24900 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24910 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
24920 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
24930 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
24940 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
24950 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
24960 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
24970 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
24980 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
24990 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
249a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
249b0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
249c0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
249d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
249e0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
249f0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
24a00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
24a10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
24a20 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
24a30 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
24a40 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
24a50 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
24a60 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
24a70 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
24a80 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
24a90 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
24aa0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24ab0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
24ac0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
24ad0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
24ae0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
24af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
24b00 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
24b10 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
24b20 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
24b30 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
24b40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
24b50 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
24b60 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
24b70 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
24b80 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
24b90 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
24ba0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
24bb0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
24bc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24bd0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
24be0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
24bf0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
24c00 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
24c10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
24c20 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
24c30 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
24c40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
24c50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
24c60 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
24c70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
24c80 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
24c90 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
24ca0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
24cb0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
24cc0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
24cd0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
24ce0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
24cf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24d00 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
24d10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
24d20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
24d30 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
24d40 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
24d50 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
24d60 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
24d70 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
24d80 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
24d90 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
24da0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
24db0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
24dc0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
24dd0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
24de0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
24df0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
24e00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
24e10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
24e20 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
24e30 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
24e40 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
24e50 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
24e60 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
24e70 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
24e80 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
24e90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
24ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24eb0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
24ec0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
24ed0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
24ee0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
24ef0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
24f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
24f10 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
24f20 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
24f30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
24f40 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
24f50 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
24f60 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
24f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24f80 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
24f90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
24fa0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
24fb0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
24fc0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
24fd0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
24fe0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
24ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25000 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
25010 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
25020 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
25030 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
25040 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
25050 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
25060 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
25070 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
25080 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
25090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
250a0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
250b0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
250c0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
250d0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
250e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
250f0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
25100 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
25110 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
25120 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
25130 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
25140 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
25150 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
25160 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
25170 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
25180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25190 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
251a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
251b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
251c0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
251d0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
251e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
251f0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
25200 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
25210 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
25220 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
25230 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
25240 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
25250 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25260 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
25270 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
25280 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
25290 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
252a0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
252b0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
252c0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
252d0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
252e0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
252f0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
25300 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25310 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
25320 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
25330 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
25340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25350 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
25360 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
25370 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
25380 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
25390 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
253a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
253b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
253c0 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
253d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
253e0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
253f0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
25400 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
25410 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
25420 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
25430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25440 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25450 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
25460 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
25470 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
25480 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
25490 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
254a0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
254b0 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
254c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
254d0 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
254e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
254f0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
25500 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
25510 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
25520 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
25530 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
25540 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
25550 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
25560 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
25570 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
25580 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
25590 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
255a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
255b0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
255c0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
255d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
255e0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
255f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
25600 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
25610 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
25620 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
25630 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
25640 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
25650 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
25660 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
25670 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25680 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
25690 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
256a0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
256b0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
256c0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
256d0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
256e0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
256f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
25700 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
25710 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
25720 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
25730 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
25740 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25750 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25760 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25770 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
25780 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
25790 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
257a0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
257b0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
257c0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
257d0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
257e0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
257f0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
25800 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
25810 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
25820 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
25830 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
25840 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
25850 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
25860 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
25870 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
25880 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
25890 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
258a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
258b0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
258c0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
258d0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
258e0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
258f0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
25900 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
25910 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
25920 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
25930 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
25940 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
25950 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
25960 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
25970 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
25980 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
25990 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
259a0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
259b0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
259c0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
259d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
259e0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
259f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
25a00 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
25a10 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
25a20 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
25a30 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
25a40 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
25a50 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
25a60 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
25a70 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
25a80 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
25a90 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
25aa0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
25ab0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
25ac0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
25ad0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
25ae0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
25af0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
25b00 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
25b10 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
25b20 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
25b30 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
25b40 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
25b50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
25b60 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
25b70 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
25b80 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
25b90 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
25ba0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
25bb0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
25bc0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
25bd0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
25be0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
25bf0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
25c00 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
25c10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
25c20 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
25c30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
25c40 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
25c50 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
25c60 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
25c70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
25c80 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
25c90 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
25ca0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
25cb0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
25cc0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
25cd0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
25ce0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
25cf0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
25d00 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
25d10 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
25d20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
25d30 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
25d40 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
25d50 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
25d60 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
25d70 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
25d80 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
25d90 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
25da0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
25db0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
25dc0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
25dd0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
25de0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
25df0 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
25e00 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
25e10 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
25e20 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
25e30 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
25e40 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
25e50 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
25e60 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
25e70 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
25e80 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
25e90 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
25ea0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
25eb0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
25ec0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ed0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
25ee0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
25ef0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
25f00 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
25f10 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
25f20 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
25f30 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
25f40 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
25f50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
25f60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
25f70 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
25f80 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
25f90 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
25fa0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
25fb0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
25fc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
25fd0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
25fe0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
25ff0 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
26000 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
26010 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
26020 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
26030 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
26040 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
26050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26060 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
26070 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
26080 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
26090 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
260a0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
260b0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
260c0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
260d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
260e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
260f0 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
26100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26110 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
26120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26130 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
26140 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
26150 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
26160 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
26170 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
26180 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
26190 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
261a0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
261b0 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
261c0 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
261d0 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
261e0 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
261f0 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
26200 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
26210 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
26220 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
26230 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
26240 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
26250 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
26260 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
26270 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
26280 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
26290 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
262a0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
262b0 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
262c0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
262d0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
262e0 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
262f0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
26300 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
26310 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
26320 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
26330 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
26340 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
26350 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
26360 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
26370 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
26380 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26390 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
263a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
263b0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
263c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
263d0 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
263e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
263f0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
26400 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
26410 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
26420 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
26430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26440 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
26450 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
26460 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
26470 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
26480 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
26490 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
264a0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
264b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
264c0 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
264d0 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
264e0 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
264f0 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
26500 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
26510 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
26520 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
26530 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
26540 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
26550 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
26560 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
26570 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
26580 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
26590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
265a0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
265b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
265c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
265d0 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
265e0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
265f0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
26600 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
26610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26620 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
26630 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
26640 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
26650 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
26660 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
26670 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
26680 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
26690 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
266a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
266b0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
266c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
266d0 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
266e0 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
266f0 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
26700 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
26710 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
26720 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
26730 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
26740 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
26750 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
26760 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
26770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26780 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
26790 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
267a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
267b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
267c0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
267d0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
267e0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
267f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
26800 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
26810 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
26820 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
26830 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
26840 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
26850 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
26860 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
26870 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
26880 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
26890 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
268a0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
268b0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
268c0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
268d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
268e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
268f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26900 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
26910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26920 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
26930 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
26940 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
26950 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
26960 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
26970 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
26980 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
26990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
269a0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
269b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
269c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
269d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
269e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
269f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
26a00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
26a10 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
26a20 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
26a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26a40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26a50 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
26a60 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26a70 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
26a80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26a90 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
26aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
26ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26ac0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
26ad0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
26ae0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
26af0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26b00 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
26b10 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
26b20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
26b30 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
26b40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
26b50 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
26b60 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
26b70 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
26b80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
26b90 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
26ba0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
26bb0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
26bc0 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
26bd0 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72   errors or.** or
26be0 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
26bf0 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
26c00 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
26c10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26c20 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
26c30 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
26c40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
26c50 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
26c60 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
26c70 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
26c80 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
26c90 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
26ca0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
26cb0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
26cc0 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
26cd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
26ce0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
26cf0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
26d00 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
26d10 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
26d20 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
26d30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26d40 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
26d50 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
26d60 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
26d70 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
26d80 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
26d90 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
26da0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
26db0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
26dc0 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
26dd0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
26de0 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
26df0 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
26e00 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
26e10 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
26e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26e30 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
26e40 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
26e50 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
26e60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
26e70 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
26e80 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
26e90 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
26ea0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
26eb0 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
26ec0 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
26ed0 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
26ee0 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
26ef0 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
26f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
26f10 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
26f20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
26f30 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
26f40 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
26f50 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
26f60 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
26f70 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
26f80 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
26f90 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
26fa0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
26fb0 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
26fc0 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
26fd0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
26fe0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
26ff0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
27000 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
27010 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
27020 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
27030 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
27040 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
27050 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
27060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27070 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
27080 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
27090 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
270a0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
270b0 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
270c0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
270d0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
270e0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
270f0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
27100 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
27110 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
27120 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
27130 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
27140 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
27150 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
27160 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
27170 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
27180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27190 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
271a0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
271b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
271c0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
271d0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
271e0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
271f0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27200 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
27210 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
27220 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
27230 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
27240 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
27250 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
27260 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
27270 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
27280 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
27290 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
272a0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
272b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
272c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
272d0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
272e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
272f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27300 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
27310 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27320 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
27330 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
27340 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
27350 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
27360 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
27370 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
27380 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
27390 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
273a0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
273b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
273c0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
273d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
273e0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
273f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27400 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
27410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
27420 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27440 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
27450 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
27460 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
27470 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
27480 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
27490 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
274a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
274b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
274c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
274d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
274e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
274f0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
27500 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
27510 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
27520 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
27530 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
27540 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
27550 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
27560 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
27570 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
27580 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
27590 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
275a0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
275b0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
275c0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
275d0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
275e0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
275f0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
27600 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 74 68 65  d for.** the the
27610 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
27620 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
27630 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
27640 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
27650 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
27660 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
27670 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
27680 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
27690 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
276a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
276b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
276c0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
276d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
276e0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
276f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
27700 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
27710 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
27720 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
27730 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
27740 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
27750 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27760 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
27770 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
27780 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
27790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
277a0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
277b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
277c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
277d0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
277e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
277f0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
27800 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
27810 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
27820 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
27830 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
27840 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
27850 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
27860 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
27870 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
27880 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
27890 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
278a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
278b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
278c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
278d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
278e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
278f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
27900 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
27910 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
27920 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
27930 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
27940 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
27950 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
27960 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
27970 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
27980 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27990 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
279a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
279b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
279c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
279d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
279e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
279f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
27a00 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
27a10 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
27a20 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
27a30 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
27a40 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
27a50 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
27a60 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
27a70 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
27a80 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
27a90 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
27aa0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
27ab0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27ac0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
27ad0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
27ae0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
27af0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
27b00 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
27b10 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
27b20 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
27b30 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
27b40 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
27b50 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
27b60 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
27b70 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
27b80 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
27b90 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
27ba0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
27bb0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
27bc0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
27bd0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
27be0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
27bf0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
27c00 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
27c10 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
27c20 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
27c30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
27c40 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
27c50 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
27c60 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
27c70 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
27c80 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
27c90 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
27ca0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
27cb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
27cc0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
27cd0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
27ce0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
27cf0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
27d00 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
27d10 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
27d20 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
27d30 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
27d40 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
27d50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
27d60 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
27d70 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
27d80 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
27d90 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
27da0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
27db0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
27dc0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
27dd0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
27de0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
27df0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
27e00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
27e10 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
27e20 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
27e30 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
27e40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
27e50 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
27e60 2a 2a 20 5e 54 68 65 20 73 65 76 65 6e 74 68 2c  ** ^The seventh,
27e70 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
27e80 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
27e90 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
27ea0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
27eb0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
27ec0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
27ed0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
27ee0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
27ef0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
27f00 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
27f10 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
27f20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
27f30 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
27f40 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
27f50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
27f60 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
27f70 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
27f80 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
27f90 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
27fa0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
27fb0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
27fc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
27fd0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
27fe0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
27ff0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
28000 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
28010 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
28020 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
28030 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
28040 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
28050 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
28060 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
28070 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
28080 28 49 66 20 74 68 65 20 74 65 6e 74 68 20 70 61  (If the tenth pa
28090 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
280a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
280b0 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
280c0 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
280d0 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
280e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
280f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
28100 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
28110 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
28120 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
28130 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
28140 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
28150 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
28160 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
28170 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
28180 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
28190 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
281a0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
281b0 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
281c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
281d0 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
281e0 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
281f0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
28200 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
28210 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
28220 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
28230 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
28240 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
28250 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
28260 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
28270 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
28280 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
28290 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
282a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
282b0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
282c0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
282d0 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
282e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
282f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
28300 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
28310 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
28320 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
28330 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
28340 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
28350 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
28360 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
28370 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
28380 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
28390 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
283a0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
283b0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
283c0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
283d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
283e0 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
283f0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28400 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
28410 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
28420 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
28430 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
28440 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
28450 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
28460 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
28470 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
28480 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
28490 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
284a0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
284b0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
284c0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
284d0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
284e0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
284f0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
28500 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
28510 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
28520 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
28530 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
28540 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
28550 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
28560 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
28570 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
28580 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
28590 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
285a0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
285b0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
285c0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
285d0 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
285e0 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
285f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28600 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
28610 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
28620 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28630 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
28640 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
28650 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
28660 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
28670 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
28680 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
28690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
286a0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
286b0 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
286c0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
286d0 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
286e0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
286f0 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
28700 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28710 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
28720 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
28730 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
28740 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
28750 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
28760 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
28770 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
28780 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
28790 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
287a0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
287b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
287c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
287d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
287e0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
287f0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
28800 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28810 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
28820 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
28830 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
28840 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
28850 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
28860 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
28870 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
28880 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
28890 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
288a0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
288b0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
288c0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
288d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
288e0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
288f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28900 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
28910 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28920 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
28930 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
28940 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
28950 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
28960 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
28970 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
28980 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
28990 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
289a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
289b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
289c0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
289d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
289e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
289f0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
28a00 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
28a10 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
28a20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
28a30 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
28a40 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
28a50 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
28a60 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
28a70 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
28a80 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
28a90 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
28aa0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
28ab0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
28ac0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
28ad0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
28ae0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
28af0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
28b00 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
28b10 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
28b20 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
28b30 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
28b40 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
28b50 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
28b60 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
28b70 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
28b80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28b90 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
28ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
28bb0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
28bc0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
28bd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
28be0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
28bf0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
28c00 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
28c10 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
28c20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
28c30 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
28c40 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
28c50 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
28c60 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
28c70 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
28c80 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
28c90 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
28ca0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
28cb0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
28cc0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
28cd0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
28ce0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
28cf0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
28d00 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
28d10 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
28d20 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
28d30 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
28d40 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
28d50 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
28d60 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
28d70 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
28d80 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
28d90 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
28da0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
28db0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28dc0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
28dd0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
28de0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
28df0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
28e00 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
28e10 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
28e20 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
28e30 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
28e40 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
28e50 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
28e60 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
28e70 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
28e80 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
28e90 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
28ea0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
28eb0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
28ec0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
28ed0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
28ee0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
28ef0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
28f00 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
28f10 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
28f20 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
28f30 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
28f40 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
28f50 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
28f60 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
28f70 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
28f80 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
28f90 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
28fa0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
28fb0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
28fc0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
28fd0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
28fe0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
28ff0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
29000 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
29010 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
29020 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
29030 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
29040 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
29050 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29060 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
29070 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29080 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
29090 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
290a0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
290b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
290c0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
290d0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
290e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
290f0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
29100 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
29110 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
29120 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29130 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
29140 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
29150 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29160 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
29170 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
29180 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
29190 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
291a0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
291b0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
291c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
291d0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
291e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
291f0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
29200 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
29210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
29220 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
29230 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
29240 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
29250 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29260 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
29270 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
29280 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
29290 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
292a0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
292b0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
292c0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
292d0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
292e0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
292f0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
29300 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
29310 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
29320 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
29330 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
29340 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
29350 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
29360 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
29370 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
29380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29390 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
293a0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
293b0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
293c0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
293d0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
293e0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
293f0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
29400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29410 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
29420 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
29430 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
29440 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
29450 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
29460 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
29470 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
29480 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
29490 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
294a0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
294b0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
294c0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
294d0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
294e0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
294f0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
29500 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
29510 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
29520 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
29530 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
29540 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
29550 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
29560 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
29570 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
29580 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
29590 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
295a0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
295b0 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
295c0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
295d0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
295e0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
295f0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
29600 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
29610 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
29620 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29630 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
29640 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
29650 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
29660 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
29670 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
29680 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
29690 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
296a0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
296b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
296c0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
296d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
296e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
296f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
29700 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
29710 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
29720 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
29730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
29740 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
29750 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
29760 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
29770 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
29780 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
29790 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
297a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
297b0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
297c0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
297d0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
297e0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
297f0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
29800 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
29810 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
29820 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
29830 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
29840 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
29850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
29860 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
29870 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
29880 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
29890 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
298a0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
298b0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
298c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
298d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
298e0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
298f0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
29900 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
29910 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
29920 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
29930 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
29940 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
29950 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
29960 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29970 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
29980 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29990 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
299a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
299b0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
299c0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
299d0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
299e0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
299f0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29a00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
29a10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29a20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
29a30 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
29a40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
29a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29a60 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
29a70 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
29a80 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
29a90 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
29aa0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
29ab0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
29ac0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
29ad0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
29ae0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
29af0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
29b00 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
29b10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
29b20 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
29b30 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
29b40 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
29b50 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
29b60 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
29b70 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
29b80 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
29b90 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
29ba0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
29bb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
29bc0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
29bd0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
29be0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
29bf0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
29c00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
29c10 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
29c20 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
29c30 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
29c40 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
29c50 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
29c60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29c70 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
29c80 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
29c90 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
29ca0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
29cb0 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
29cc0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
29cd0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
29ce0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
29cf0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
29d00 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
29d10 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
29d20 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
29d30 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
29d40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
29d50 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
29d60 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
29d70 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
29d80 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
29d90 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
29da0 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
29db0 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
29dc0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
29dd0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
29de0 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
29df0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
29e00 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
29e10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
29e20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
29e30 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
29e40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
29e50 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20  nter if N is.** 
29e60 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
29e70 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
29e80 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
29e90 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
29ea0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
29eb0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
29ec0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
29ed0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29ee0 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
29ef0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
29f00 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
29f10 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
29f20 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
29f30 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
29f40 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
29f50 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
29f60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
29f70 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
29f80 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
29f90 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
29fa0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
29fb0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
29fc0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a  * allocation.)^.
29fd0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
29fe0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
29ff0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
2a000 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
2a010 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2a020 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
2a030 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
2a040 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
2a050 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
2a060 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2a070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2a080 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2a090 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
2a0a0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
2a0b0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
2a0c0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
2a0d0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
2a0e0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
2a0f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2a100 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
2a110 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
2a120 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
2a130 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2a140 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2a150 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
2a160 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
2a170 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2a180 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2a190 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2a1a0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
2a1b0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
2a1c0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
2a1d0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
2a1e0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
2a1f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a200 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
2a210 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a220 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2a230 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
2a240 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
2a250 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
2a260 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
2a270 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2a280 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a290 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2a2a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a2b0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2a2c0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2a2d0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2a2e0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2a2f0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2a300 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
2a310 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
2a320 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2a330 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2a340 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
2a350 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a360 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2a370 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2a380 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
2a390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2a3a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a3b0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2a3c0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
2a3d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2a3e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2a3f0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
2a400 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2a410 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2a420 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
2a430 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a440 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
2a450 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
2a460 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a470 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
2a480 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2a490 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2a4a0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
2a4b0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
2a4c0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
2a4d0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2a4e0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
2a4f0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2a500 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2a510 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a520 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2a530 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
2a540 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
2a550 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2a560 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
2a570 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
2a580 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2a590 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
2a5a0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
2a5b0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
2a5c0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
2a5d0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
2a5e0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
2a5f0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2a600 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
2a610 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
2a620 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
2a630 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
2a640 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
2a650 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
2a660 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
2a670 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
2a680 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
2a690 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
2a6a0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
2a6b0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
2a6c0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
2a6d0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
2a6e0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
2a6f0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
2a700 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
2a710 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2a720 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2a730 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2a740 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2a750 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2a760 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2a770 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2a780 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2a790 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2a7a0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2a7b0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2a7c0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2a7d0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2a7e0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2a7f0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2a800 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2a810 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
2a820 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2a830 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2a840 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2a850 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2a860 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2a870 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2a880 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2a890 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2a8a0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2a8b0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2a8c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a8d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
2a8e0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
2a8f0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
2a900 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
2a910 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
2a920 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
2a930 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
2a940 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
2a950 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
2a960 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
2a970 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
2a980 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
2a990 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a9a0 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
2a9b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2a9c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
2a9d0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
2a9e0 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
2a9f0 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
2aa00 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
2aa10 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2aa20 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
2aa30 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
2aa40 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
2aa50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2aa60 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
2aa70 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
2aa80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2aa90 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
2aaa0 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
2aab0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
2aac0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
2aad0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
2aae0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
2aaf0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2ab00 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
2ab10 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
2ab20 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2ab30 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
2ab40 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
2ab50 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
2ab60 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2ab70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2ab80 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
2ab90 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
2aba0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
2abb0 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
2abc0 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
2abd0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
2abe0 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
2abf0 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
2ac00 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
2ac10 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
2ac20 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
2ac30 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
2ac40 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
2ac50 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
2ac60 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
2ac70 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
2ac80 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
2ac90 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
2aca0 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
2acb0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
2acc0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
2acd0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
2ace0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
2acf0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
2ad00 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
2ad10 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
2ad20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
2ad30 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
2ad40 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
2ad50 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2ad60 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ad70 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2ad80 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
2ad90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2ada0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
2adb0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2adc0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2add0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
2ade0 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
2adf0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2ae00 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
2ae10 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
2ae20 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
2ae30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
2ae40 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
2ae50 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
2ae60 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
2ae70 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
2ae80 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
2ae90 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
2aea0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
2aeb0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
2aec0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
2aed0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2aee0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
2aef0 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
2af00 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
2af10 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
2af20 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
2af30 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
2af40 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
2af50 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
2af60 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
2af70 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2af80 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
2af90 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
2afa0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2afb0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2afc0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2afd0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2afe0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2aff0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2b000 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2b010 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2b020 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2b030 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2b040 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2b050 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2b060 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2b070 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2b080 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2b090 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2b0a0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2b0b0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2b0c0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2b0d0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2b0e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2b0f0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2b100 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2b110 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2b120 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2b130 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2b140 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2b150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b160 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2b170 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2b180 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
2b190 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
2b1a0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
2b1b0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
2b1c0 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
2b1d0 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
2b1e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2b1f0 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
2b200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b210 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2b220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b230 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
2b240 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2b250 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2b260 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2b270 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
2b280 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
2b290 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
2b2a0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
2b2b0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
2b2c0 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
2b2d0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
2b2e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2b2f0 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
2b300 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
2b310 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2b320 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2b330 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
2b340 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2b350 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
2b360 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2b370 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2b380 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2b390 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2b3a0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
2b3b0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
2b3c0 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
2b3d0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2b3e0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
2b3f0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
2b400 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
2b410 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2b420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b430 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2b440 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
2b450 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
2b460 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2b470 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b480 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2b490 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
2b4a0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
2b4b0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
2b4c0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
2b4d0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
2b4e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2b4f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b500 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2b510 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
2b520 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
2b530 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
2b540 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b550 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
2b560 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b570 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
2b580 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
2b590 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2b5a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b5b0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
2b5c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b5d0 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
2b5e0 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
2b5f0 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
2b600 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
2b610 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
2b620 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
2b630 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
2b640 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
2b650 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
2b660 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b670 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
2b680 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2b690 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
2b6a0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
2b6b0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
2b6c0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
2b6d0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
2b6e0 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
2b6f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2b700 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
2b710 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
2b720 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
2b730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b740 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
2b750 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
2b760 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
2b770 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2b780 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2b790 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
2b7a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2b7b0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2b7c0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
2b7d0 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
2b7e0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
2b7f0 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
2b800 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
2b810 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
2b820 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2b830 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2b840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b850 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
2b860 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2b870 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
2b880 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2b890 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
2b8a0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
2b8b0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
2b8c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2b8d0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
2b8e0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
2b8f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b900 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
2b910 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b920 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
2b930 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
2b940 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2b950 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2b960 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2b970 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2b980 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2b990 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2b9a0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2b9b0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2b9c0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2b9d0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
2b9e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b9f0 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
2ba00 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
2ba10 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
2ba20 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
2ba30 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
2ba40 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
2ba50 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
2ba60 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
2ba70 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
2ba80 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
2ba90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2baa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bab0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2bac0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2bad0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
2bae0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
2baf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
2bb00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bb10 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
2bb20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
2bb30 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
2bb40 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
2bb50 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
2bb60 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
2bb70 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
2bb80 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
2bb90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2bba0 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
2bbb0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
2bbc0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
2bbd0 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
2bbe0 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
2bbf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
2bc00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2bc10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2bc20 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
2bc30 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2bc40 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2bc50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bc60 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2bc70 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
2bc80 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2bc90 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2bca0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2bcb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2bcc0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
2bcd0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2bce0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2bcf0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2bd00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2bd10 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
2bd20 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2bd30 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2bd40 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2bd50 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2bd60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2bd70 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
2bd80 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2bd90 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2bda0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bdb0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bdc0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
2bdd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bde0 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
2bdf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2be00 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
2be10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2be20 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
2be30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2be40 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
2be50 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
2be60 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
2be70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2be80 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2be90 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
2bea0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
2beb0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
2bec0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2bed0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
2bee0 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
2bef0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
2bf00 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
2bf10 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
2bf20 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
2bf30 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
2bf40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
2bf50 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
2bf60 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
2bf70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2bf80 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
2bf90 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
2bfa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2bfb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2bfc0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2bfd0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2bfe0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
2bff0 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
2c000 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
2c010 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
2c020 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
2c030 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
2c040 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
2c050 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2c060 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c070 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2c080 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2c090 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
2c0a0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
2c0b0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
2c0c0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
2c0d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2c0e0 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
2c0f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2c100 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
2c110 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  n result..** ^If
2c120 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2c130 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2c140 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2c150 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2c160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2c170 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
2c180 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2c190 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
2c1a0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
2c1b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2c1c0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
2c1d0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
2c1e0 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
2c1f0 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
2c200 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2c210 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2c220 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2c230 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2c240 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
2c250 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2c260 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2c270 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2c280 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
2c290 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
2c2a0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
2c2b0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
2c2c0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
2c2d0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
2c2e0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
2c2f0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
2c300 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
2c310 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2c320 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
2c330 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
2c340 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
2c350 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2c360 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2c370 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2c380 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2c390 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2c3a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2c3b0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2c3c0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
2c3d0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
2c3e0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
2c3f0 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
2c400 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
2c410 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
2c420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c430 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
2c440 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2c450 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c460 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2c470 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2c480 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2c490 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c4a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c4b0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
2c4c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c4d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c4e0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
2c4f0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2c500 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
2c510 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2c520 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
2c530 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2c540 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2c550 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
2c560 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2c570 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
2c580 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
2c590 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
2c5a0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
2c5b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c5c0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
2c5d0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2c5e0 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
2c5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c600 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
2c610 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
2c620 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2c630 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c640 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
2c650 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
2c660 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
2c670 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c680 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
2c690 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
2c6a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
2c6b0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2c6c0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
2c6d0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
2c6e0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
2c6f0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
2c700 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c710 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2c720 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
2c730 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
2c740 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
2c750 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2c760 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
2c770 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2c780 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
2c790 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2c7a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2c7b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2c7c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c7d0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2c7e0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
2c7f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c800 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
2c810 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2c820 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
2c830 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2c840 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
2c850 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2c860 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2c870 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2c880 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
2c890 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
2c8a0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2c8b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c8c0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
2c8d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2c8e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2c8f0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
2c900 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2c910 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c920 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
2c930 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2c940 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2c950 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
2c960 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
2c970 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
2c980 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2c990 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
2c9a0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2c9b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2c9c0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2c9d0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2c9e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2c9f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2ca00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ca10 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2ca20 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2ca30 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2ca40 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2ca50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2ca60 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
2ca70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2ca80 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2ca90 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2caa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2cab0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
2cac0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2cad0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2cae0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2caf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2cb00 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
2cb10 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
2cb20 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
2cb30 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
2cb40 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
2cb50 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
2cb60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2cb70 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
2cb80 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
2cb90 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
2cba0 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c  ons add, remove,
2cbb0 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f   or modify a [co
2cbc0 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61  llation] associa
2cbd0 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
2cbe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cbf0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
2cc00 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2cc10 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2cc20 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
2cc30 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46  llation is a UTF
2cc40 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2cc50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2cc60 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2cc70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2cc80 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2cc90 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2cca0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
2ccb0 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71  yte order for sq
2ccc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ccd0 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e  lation16()..** ^
2cce0 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20  Collation names 
2ccf0 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75  that compare equ
2cd00 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  al according to 
2cd10 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d  [sqlite3_strnicm
2cd20 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  p()] are.** cons
2cd30 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65  idered to be the
2cd40 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a   same name..**.*
2cd50 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72  * ^(The third ar
2cd60 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70  gument (eTextRep
2cd70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2cd80 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a   the constants:.
2cd90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2cda0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2cdb0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2cdc0 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16LE],.** <li>
2cdd0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
2cde0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
2cdf0 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a  TE_UTF16], or.**
2ce00 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2ce10 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a  F16_ALIGNED]..**
2ce20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65   </ul>)^.** ^The
2ce30 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
2ce40 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  nt determines th
2ce50 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74  e encoding of st
2ce60 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20  rings passed.** 
2ce70 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
2ce80 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2ce90 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a  ck, xCallback..*
2cea0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
2ceb0 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54  TF16] and [SQLIT
2cec0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
2ced0 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78   values for eTex
2cee0 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74  tRep.** force st
2cef0 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31  rings to be UTF1
2cf00 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79  6 with native by
2cf10 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68  te order..** ^Th
2cf20 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
2cf30 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66  ALIGNED] value f
2cf40 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63  or eTextRep forc
2cf50 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  es strings to be
2cf60 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65  gin.** on an eve
2cf70 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a  n byte address..
2cf80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
2cf90 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67  h argument, pArg
2cfa0 2c 20 69 73 20 61 20 61 70 70 6c 69 63 61 74 69  , is a applicati
2cfb0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
2cfc0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
2cfd0 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
2cfe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2cff0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
2d000 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2d010 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
2d020 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
2d030 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
2d040 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
2d050 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2d060 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
2d070 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d080 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
2d090 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
2d0a0 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
2d0b0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
2d0c0 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
2d0d0 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
2d0e0 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
2d0f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
2d100 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
2d110 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
2d120 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
2d130 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
2d140 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
2d150 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
2d160 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2d170 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
2d180 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
2d190 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
2d1a0 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
2d1b0 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
2d1c0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
2d1d0 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
2d1e0 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
2d1f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2d200 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
2d210 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
2d220 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
2d230 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
2d240 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
2d250 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
2d260 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
2d270 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
2d280 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
2d290 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
2d2a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d2b0 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
2d2c0 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
2d2d0 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
2d2e0 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
2d2f0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
2d300 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
2d310 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
2d320 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
2d330 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
2d340 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
2d350 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d360 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 20 72 65  on must alway re
2d370 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
2d380 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
2d390 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
2d3a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
2d3b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2d3c0 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
2d3d0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
2d3e0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
2d3f0 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
2d400 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
2d410 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
2d420 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
2d430 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
2d440 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
2d450 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
2d460 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
2d470 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
2d480 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
2d490 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
2d4a0 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
2d4b0 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
2d4c0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2d4d0 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
2d4e0 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
2d4f0 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
2d500 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
2d510 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
2d520 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
2d530 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
2d540 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
2d550 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
2d560 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
2d570 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
2d580 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
2d590 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
2d5a0 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
2d5b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
2d5c0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
2d5d0 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
2d5e0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
2d5f0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2d600 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d610 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2d620 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
2d630 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
2d640 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2d650 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
2d660 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
2d670 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
2d680 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
2d690 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
2d6a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2d6b0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
2d6c0 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
2d6d0 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
2d6e0 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
2d6f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2d700 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
2d710 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
2d720 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
2d730 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
2d740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d750 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
2d760 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2d770 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
2d780 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
2d790 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
2d7a0 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
2d7b0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
2d7c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2d7d0 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
2d7e0 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
2d7f0 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
2d800 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2d810 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2d820 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
2d830 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
2d840 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
2d850 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
2d860 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
2d870 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2d880 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
2d890 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
2d8a0 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
2d8b0 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
2d8c0 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
2d8d0 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
2d8e0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
2d8f0 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
2d900 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
2d910 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
2d920 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
2d930 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
2d940 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
2d950 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
2d960 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
2d970 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
2d980 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
2d990 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2d9a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d9b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2d9c0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
2d9d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d9e0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2d9f0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2da00 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2da10 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2da20 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
2da30 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2da40 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2da50 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2da60 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2da70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2da80 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2da90 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2daa0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2dab0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2dac0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
2dad0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2dae0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2daf0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2db00 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2db10 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
2db20 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2db30 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
2db40 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2db50 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
2db60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2db70 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
2db80 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2db90 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2dba0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2dbb0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2dbc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
2dbd0 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
2dbe0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
2dbf0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
2dc00 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
2dc10 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2dc20 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
2dc30 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
2dc40 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
2dc50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
2dc60 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
2dc70 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
2dc80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dc90 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
2dca0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
2dcb0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
2dcc0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
2dcd0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2dce0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
2dcf0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
2dd00 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2dd10 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2dd20 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
2dd30 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
2dd40 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
2dd50 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
2dd60 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
2dd70 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
2dd80 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
2dd90 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2dda0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
2ddb0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
2ddc0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
2ddd0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
2dde0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ddf0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
2de00 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
2de10 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
2de20 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
2de30 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
2de40 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
2de50 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
2de60 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
2de70 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
2de80 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
2de90 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2dea0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2deb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2dec0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2ded0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2dee0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
2def0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2df00 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2df10 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
2df20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2df30 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2df40 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2df50 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
2df60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2df70 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
2df80 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
2df90 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
2dfa0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
2dfb0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
2dfc0 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
2dfd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2dfe0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
2dff0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
2e000 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
2e010 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2e020 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
2e030 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
2e040 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
2e050 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2e060 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e070 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
2e080 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2e090 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
2e0a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2e0b0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
2e0c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2e0d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2e0e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e0f0 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
2e100 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2e110 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2e120 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
2e130 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2e140 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
2e150 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2e160 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
2e170 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2e180 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2e190 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
2e1a0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
2e1b0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
2e1c0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
2e1d0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
2e1e0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
2e1f0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
2e200 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
2e210 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
2e220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2e230 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2e240 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2e250 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2e260 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2e270 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2e280 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
2e290 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e2a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e2b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2e2c0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2e2d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2e2e0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2e2f0 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
2e300 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
2e310 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
2e320 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
2e330 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
2e340 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
2e350 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
2e360 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
2e370 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
2e380 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
2e390 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
2e3a0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
2e3b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2e3c0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2e3d0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2e3e0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2e3f0 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2e400 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2e410 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
2e420 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e440 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2e450 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2e460 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2e470 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2e480 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
2e490 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2e4a0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
2e4b0 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
2e4c0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2e4d0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2e4e0 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
2e4f0 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2e500 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2e510 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
2e520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2e530 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
2e540 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
2e550 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
2e560 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
2e570 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
2e580 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2e590 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
2e5a0 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
2e5b0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2e5c0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2e5d0 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
2e5e0 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2e5f0 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2e600 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
2e610 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
2e620 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
2e630 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
2e640 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
2e650 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2e660 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
2e670 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
2e680 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
2e690 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2e6a0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2e6b0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2e6c0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2e6d0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2e6e0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2e6f0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2e700 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2e710 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2e720 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
2e730 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2e740 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2e750 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2e760 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
2e770 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2e780 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2e790 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2e7a0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
2e7b0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
2e7c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2e7d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2e7e0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2e7f0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2e800 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2e810 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2e820 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2e830 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2e840 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2e850 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2e860 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2e870 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2e880 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
2e890 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
2e8a0 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
2e8b0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
2e8c0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
2e8d0 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
2e8e0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
2e8f0 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
2e900 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2e910 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
2e920 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
2e930 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
2e940 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
2e950 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
2e960 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2e970 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2e980 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2e990 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
2e9a0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
2e9b0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
2e9c0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2e9d0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2e9e0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2e9f0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2ea00 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2ea10 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
2ea20 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2ea30 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2ea40 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2ea50 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
2ea60 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
2ea70 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
2ea80 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
2ea90 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
2eaa0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
2eab0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
2eac0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2ead0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
2eae0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
2eaf0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
2eb00 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
2eb10 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
2eb20 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
2eb30 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2eb40 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2eb50 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
2eb60 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
2eb70 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
2eb80 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2eb90 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2eba0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
2ebb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ebc0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
2ebd0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
2ebe0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
2ebf0 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
2ec00 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
2ec10 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2ec20 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
2ec30 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
2ec40 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
2ec50 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
2ec60 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
2ec70 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
2ec80 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2ec90 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
2eca0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
2ecb0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
2ecc0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
2ecd0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2ece0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2ecf0 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
2ed00 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
2ed10 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
2ed20 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2ed30 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2ed40 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
2ed50 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
2ed60 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2ed70 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2ed80 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
2ed90 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
2eda0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
2edb0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
2edc0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
2edd0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2ede0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
2edf0 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
2ee00 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
2ee10 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
2ee20 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
2ee30 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
2ee40 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
2ee50 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
2ee60 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
2ee70 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
2ee80 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
2ee90 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
2eea0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2eeb0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2eec0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
2eed0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
2eee0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2eef0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2ef00 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2ef10 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
2ef20 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
2ef30 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
2ef40 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
2ef50 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
2ef60 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
2ef70 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
2ef80 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
2ef90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2efa0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
2efb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2efc0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
2efd0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
2efe0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
2eff0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
2f000 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
2f010 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
2f020 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
2f030 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
2f040 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
2f050 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2f060 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2f070 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2f080 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
2f090 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2f0a0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2f0b0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2f0c0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2f0d0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2f0e0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2f0f0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2f100 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2f110 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2f120 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2f130 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2f140 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2f150 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2f160 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2f170 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2f180 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2f190 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2f1a0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2f1b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2f1c0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2f1d0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2f1e0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2f1f0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2f200 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2f210 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2f220 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2f230 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2f240 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2f250 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2f260 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2f270 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2f280 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2f290 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2f2a0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2f2b0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2f2c0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2f2d0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2f2e0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2f2f0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2f300 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
2f310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2f320 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
2f330 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
2f340 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2f350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f360 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
2f370 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2f380 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f390 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2f3a0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
2f3b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f3c0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68  t] belongs.  ^Th
2f3d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f3e0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
2f3f0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
2f400 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
2f410 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2f420 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
2f430 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
2f440 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2f450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2f460 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
2f470 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
2f480 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
2f490 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
2f4a0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2f4b0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2f4c0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2f4d0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
2f4e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2f4f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2f500 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
2f510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2f520 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2f530 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2f540 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
2f550 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
2f560 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
2f570 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
2f580 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
2f590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f5a0 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74   pDb.  ^If pStmt
2f5b0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
2f5c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f5d0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2f5e0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
2f5f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f600 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
2f610 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
2f620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
2f630 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72  .  ^If no prepar
2f640 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2f650 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2f660 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2f670 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2f680 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2f690 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2f6a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2f6b0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2f6c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2f6d0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2f6e0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2f6f0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2f700 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2f710 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2f720 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2f730 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69  pointer..*/.sqli
2f740 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
2f750 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
2f760 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
2f770 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2f780 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f790 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
2f7a0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
2f7b0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2f7c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2f7d0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
2f7e0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2f7f0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2f800 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2f810 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2f820 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2f830 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
2f840 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
2f850 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2f860 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2f870 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2f880 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2f890 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2f8a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2f8b0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2f8c0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2f8d0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2f8e0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2f8f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2f900 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2f910 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2f920 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
2f930 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
2f940 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
2f950 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2f960 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2f970 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
2f980 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
2f990 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2f9a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2f9b0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2f9c0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
2f9d0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
2f9e0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
2f9f0 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
2fa00 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
2fa10 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
2fa20 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
2fa30 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
2fa40 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
2fa50 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
2fa60 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2fa70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2fa80 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
2fa90 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2faa0 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
2fab0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
2fac0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
2fad0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2fae0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
2faf0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2fb00 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2fb10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fb20 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2fb30 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2fb40 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
2fb50 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
2fb60 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2fb70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2fb80 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2fb90 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2fba0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2fbb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2fbc0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2fbd0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2fbe0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2fbf0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2fc00 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2fc10 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2fc20 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2fc30 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2fc40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fc50 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2fc60 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2fc70 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2fc80 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2fc90 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2fca0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2fcb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2fcc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fcd0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2fce0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2fcf0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2fd00 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2fd10 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2fd20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2fd30 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
2fd40 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
2fd50 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
2fd60 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
2fd70 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2fd80 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2fd90 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
2fda0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
2fdb0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
2fdc0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
2fdd0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
2fde0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
2fdf0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
2fe00 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
2fe10 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
2fe20 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
2fe30 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
2fe40 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2fe50 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2fe60 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2fe70 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2fe80 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2fe90 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2fea0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2feb0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2fec0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2fed0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
2fee0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
2fef0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ff00 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
2ff10 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
2ff20 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
2ff30 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
2ff40 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
2ff50 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
2ff60 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
2ff70 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
2ff80 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
2ff90 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
2ffa0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
2ffb0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
2ffc0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2ffd0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2ffe0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
2fff0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
30000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
30010 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
30020 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
30030 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
30040 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
30050 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
30060 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
30070 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
30080 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
30090 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
300a0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
300b0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
300c0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
300d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
300e0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
300f0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
30100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30110 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
30120 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
30130 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
30140 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
30150 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
30160 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
30170 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
30180 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
30190 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
301a0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
301b0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
301c0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
301d0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
301e0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
301f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
30200 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
30210 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
30220 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
30230 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
30240 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
30250 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
30260 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
30270 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
30280 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
30290 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
302a0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
302b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
302c0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
302d0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
302e0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
302f0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
30300 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
30310 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
30320 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
30330 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
30340 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
30350 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
30360 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
30370 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
30380 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
30390 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
303a0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
303b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
303c0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
303d0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
303e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
303f0 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
30400 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
30410 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
30420 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
30430 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
30440 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
30450 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
30460 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
30470 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
30480 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
30490 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
304a0 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
304b0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
304c0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
304d0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
304e0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
304f0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
30500 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
30510 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
30520 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
30530 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
30540 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
30550 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
30560 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
30570 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
30580 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
30590 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
305a0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
305b0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
305c0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
305d0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
305e0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
305f0 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
30600 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
30610 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
30620 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
30630 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
30640 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
30650 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
30660 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
30670 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
30680 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
30690 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
306a0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
306b0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
306c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
306d0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
306e0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
306f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
30700 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
30710 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
30720 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
30730 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
30740 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
30750 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
30760 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
30770 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
30780 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
30790 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
307a0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
307b0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
307c0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
307d0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
307e0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
307f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30800 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
30810 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
30820 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
30830 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
30840 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
30850 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
30860 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
30870 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
30880 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
30890 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
308a0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
308b0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
308c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
308d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
308e0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
308f0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
30900 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
30910 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
30920 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
30930 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
30940 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
30950 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
30960 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
30970 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
30980 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
30990 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
309a0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
309b0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
309c0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
309d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
309e0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
309f0 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
30a00 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
30a10 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
30a20 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
30a30 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
30a40 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
30a50 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
30a60 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
30a70 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
30a80 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
30a90 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
30aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
30ab0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
30ac0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
30ad0 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
30ae0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
30af0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
30b00 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
30b10 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
30b20 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
30b30 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
30b40 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
30b50 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
30b60 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
30b70 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
30b80 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
30b90 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
30ba0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
30bb0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
30bc0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
30bd0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
30be0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
30bf0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
30c00 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
30c10 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
30c20 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
30c30 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
30c40 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
30c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
30c60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
30c70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
30c80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
30c90 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
30ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30cb0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
30cc0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
30cd0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
30ce0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
30cf0 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
30d00 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
30d10 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
30d20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
30d30 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
30d40 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
30d50 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
30d60 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
30d70 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
30d80 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
30d90 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
30da0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
30db0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
30dc0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
30dd0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
30de0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
30df0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
30e00 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
30e10 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
30e20 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
30e30 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
30e40 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
30e50 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
30e60 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
30e70 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
30e80 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
30e90 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
30ea0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
30eb0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
30ec0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
30ed0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
30ee0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
30ef0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30f00 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
30f10 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
30f20 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
30f30 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
30f40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
30f50 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
30f60 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
30f70 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
30f80 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
30f90 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
30fa0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
30fb0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
30fc0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
30fd0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
30fe0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
30ff0 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
31000 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31010 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
31020 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
31030 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
31040 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
31050 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
31060 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
31070 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
31080 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
31090 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
310a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
310b0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
310c0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
310d0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
310e0 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  NT]..*/.int sqli
310f0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
31100 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
31110 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
31120 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
31130 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
31140 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
31150 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
31160 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
31170 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
31180 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
31190 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
311a0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
311b0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
311c0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
311d0 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
311e0 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
311f0 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
31200 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
31210 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
31220 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
31230 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
31240 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
31250 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
31260 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
31270 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
31280 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
31290 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
312a0 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
312b0 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
312c0 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
312d0 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
312e0 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
312f0 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
31300 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
31310 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
31320 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
31330 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
31340 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
31350 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
31360 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
31370 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
31380 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
31390 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
313a0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
313b0 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
313c0 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
313d0 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68  he call.  ^If th
313e0 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
313f0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
31400 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
31410 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
31420 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
31430 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
31440 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
31450 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
31460 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
31470 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
31480 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
31490 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
314a0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
314b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
314c0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
314d0 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
314e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
314f0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
31500 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
31510 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
31520 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
31530 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
31540 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
31550 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
31560 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
31570 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
31580 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
31590 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
315a0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
315b0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
315c0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
315d0 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
315e0 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
315f0 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
31600 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
31610 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
31620 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
31630 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
31640 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
31650 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
31660 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
31670 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
31680 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
31690 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
316a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
316b0 73 70 65 63 69 66 65 64 20 75 73 69 6e 67 0a 2a  specifed using.*
316c0 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  *      [sqlite3_
316d0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
316e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e  CONFIG_PCACHE],.
316f0 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ..)..** <li> The
31700 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f   page cache allo
31710 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f  cates from its o
31720 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73  wn memory pool s
31730 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20  upplied.**      
31740 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  by [sqlite3_conf
31750 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
31760 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e  IG_PAGECACHE],..
31770 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a  .) rather than.*
31780 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20  *      from the 
31790 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  heap..** </ul>)^
317a0 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67  .**.** Beginning
317b0 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
317c0 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20  sion 3.7.3, the 
317d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
317e0 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72  is enforced.** r
317f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
31800 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
31810 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
31820 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
31830 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
31840 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f  e option is invo
31850 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49  ked.  With [SQLI
31860 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
31870 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a  _MANAGEMENT],.**
31880 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
31890 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
318a0 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79   on every memory
318b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69   allocation.  Wi
318c0 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  thout.** [SQLITE
318d0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
318e0 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20  ANAGEMENT], the 
318f0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
31900 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64  is only enforced
31910 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  .** when memory 
31920 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  is allocated by 
31930 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20  the page cache. 
31940 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74   Testing suggest
31950 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a  s that because.*
31960 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  * the page cache
31970 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e   is the predomin
31980 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20  ate memory user 
31990 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a  in SQLite, most.
319a0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
319b0 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65  will achieve ade
319c0 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20  quate soft heap 
319d0 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e  limit enforcemen
319e0 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65  t without.** the
319f0 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   use of [SQLITE_
31a00 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
31a10 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a  NAGEMENT]..**.**
31a20 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   The circumstanc
31a30 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53  es under which S
31a40 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72  QLite will enfor
31a50 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ce the soft heap
31a60 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68   limit may.** ch
31a70 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20  anges in future 
31a80 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
31a90 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  te..*/.sqlite3_i
31aa0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66  nt64 sqlite3_sof
31ab0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73  t_heap_limit64(s
31ac0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b  qlite3_int64 N);
31ad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31ae0 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f 66  : Deprecated Sof
31af0 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74  t Heap Limit Int
31b00 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43  erface.** DEPREC
31b10 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ATED.**.** This 
31b20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64 20  is a deprecated 
31b30 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b  version of the [
31b40 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
31b50 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
31b60 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69 73  interface.  This
31b70 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76   routine is prov
31b80 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  ided for histori
31b90 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
31ba0 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  y.** only.  All 
31bb0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
31bc0 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a   should use the.
31bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  ** [sqlite3_soft
31be0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
31bf0 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68 65   interface rathe
31c00 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e  r than this one.
31c10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
31c20 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
31c30 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
31c40 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a  it(int N);.../*.
31c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
31c60 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
31c70 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
31c80 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  A Table.**.** ^T
31c90 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
31ca0 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
31cb0 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
31cc0 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
31cd0 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
31ce0 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
31cf0 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
31d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
31d10 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
31d20 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
31d30 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
31d40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75  .**.** ^The colu
31d50 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
31d60 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
31d70 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
31d80 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a   parameters to.*
31d90 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
31da0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
31db0 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
31dc0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31dd0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
31de0 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
31df0 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  ", or an attache
31e00 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
31e10 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
31e20 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
31e30 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73   NULL. ^If it is
31e40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
31e50 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
31e60 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
31e70 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
31e80 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
31e90 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62  algorithm used b
31ea0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  y the database e
31eb0 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f  ngine to.** reso
31ec0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
31ed0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
31ee0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
31ef0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
31f00 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
31f10 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
31f20 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
31f30 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
31f40 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
31f50 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
31f60 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
31f70 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
31f80 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
31f90 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72  * ^Metadata is r
31fa0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
31fb0 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
31fc0 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
31fd0 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
31fe0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
31ff0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
32000 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79  s function. ^Any
32010 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
32020 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
32030 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
32040 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
32050 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
32060 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
32070 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f  ed..**.** ^(<blo
32080 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
32090 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
320a0 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d  * <tr><th> Param
320b0 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74  eter <th> Output
320c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44  <br>Type <th>  D
320d0 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a  escription.**.**
320e0 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74   <tr><td> 5th <t
320f0 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
32100 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a  td> Data type.**
32110 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74   <tr><td> 6th <t
32120 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
32130 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61  td> Name of defa
32140 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
32150 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74  quence.** <tr><t
32160 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 7th <td> int 
32170 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
32180 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20  e if column has 
32190 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  a NOT NULL const
321a0 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  raint.** <tr><td
321b0 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 8th <td> int  
321c0 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
321d0 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61   if column is pa
321e0 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  rt of the PRIMAR
321f0 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64  Y KEY.** <tr><td
32200 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 9th <td> int  
32210 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
32220 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41   if column is [A
32230 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a  UTOINCREMENT].**
32240 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
32250 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
32260 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70  ** ^The memory p
32270 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
32280 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
32290 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
322a0 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
322b0 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
322c0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
322d0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
322e0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
322f0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
32300 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
32310 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
32320 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
32330 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
32340 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  w, an [error cod
32350 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
32360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
32370 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
32380 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
32390 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
323a0 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52  d an.** [INTEGER
323b0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
323c0 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
323d0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
323e0 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
323f0 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
32400 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
32410 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
32420 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49  ared column. ^(I
32430 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
32440 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
32450 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52  ared [INTEGER PR
32460 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
32470 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
32480 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
32490 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c   are set as foll
324a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
324b0 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
324c0 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
324d0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
324e0 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
324f0 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
32500 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
32510 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
32520 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
32530 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a   0.** </pre>)^.*
32540 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
32550 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e  tion may load on
32560 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61  e or more schema
32570 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  s from database 
32580 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20  files. If an.** 
32590 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
325a0 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73  ing this process
325b0 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75  , or if the requ
325c0 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63  ested table or c
325d0 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20  olumn.** cannot 
325e0 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72  be found, an [er
325f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
32600 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
32610 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a  or message left.
32620 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ** in the [datab
32630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32640 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
32650 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
32660 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a  rrmsg()).)^.**.*
32670 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f  * ^This API is o
32680 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
32690 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
326a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
326b0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
326c0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
326d0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
326e0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
326f0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
32700 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
32710 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
32720 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
32730 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
32740 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
32750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32760 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
32770 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
32780 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
32790 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
327a0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
327b0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
327c0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
327d0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
327e0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
327f0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
32800 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
32810 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
32820 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
32830 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
32840 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
32850 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
32860 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
32870 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
32880 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
32890 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
328a0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
328b0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
328c0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
328d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
328e0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
328f0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
32900 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
32910 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
32920 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
32930 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
32940 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
32950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32960 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
32970 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  sion.**.** ^This
32980 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
32990 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
329a0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
329b0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
329c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
329d0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
329e0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
329f0 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
32a00 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78   an.** SQLite ex
32a10 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
32a20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
32a30 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
32a40 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f  ** ^The entry po
32a50 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a  int is zProc..**
32a60 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30   ^zProc may be 0
32a70 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
32a80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
32a90 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64  entry point.** d
32aa0 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
32ab0 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
32ac0 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  it"..** ^The sql
32ad0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
32ae0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
32af0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
32b00 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
32b10 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
32b20 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
32b30 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
32b40 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
32b50 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
32b60 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
32b70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32b80 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
32b90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
32ba0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
32bb0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
32bc0 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61  with error messa
32bd0 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
32be0 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61  n memory.** obta
32bf0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
32c00 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68  e3_malloc()]. Th
32c10 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
32c20 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65  on.** should fre
32c30 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
32c40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32c50 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
32c60 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
32c70 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
32c80 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  led using.** [sq
32c90 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
32ca0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  d_extension()] p
32cb0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
32cc0 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68  this API,.** oth
32cd0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
32ce0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
32cf0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
32d00 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
32d10 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74  sion() SQL funct
32d20 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ion]..*/.int sql
32d30 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
32d40 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
32d50 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
32d60 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
32d70 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
32d80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32d90 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
32da0 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
32db0 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
32dc0 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
32dd0 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
32de0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
32df0 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
32e00 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
32e10 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
32e20 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
32e30 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
32e40 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
32e50 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
32e60 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
32e70 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
32e80 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
32e90 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
32ea0 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  * ^So as not to 
32eb0 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
32ec0 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
32ed0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
32ee0 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
32ef0 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
32f00 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
32f10 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
32f20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
32f30 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
32f40 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
32f50 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
32f60 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
32f70 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f  ng API.** is pro
32f80 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
32f90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
32fa0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
32fb0 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66  hanism on and of
32fc0 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73  f..**.** ^Extens
32fd0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
32fe0 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53  ff by default. S
32ff0 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e  ee ticket #1863.
33000 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71  .** ^Call the sq
33010 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
33020 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
33030 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66  utine with onoff
33040 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65  ==1.** to turn e
33050 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
33060 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20   on and call it 
33070 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
33080 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b   turn.** it back
33090 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69   off again..*/.i
330a0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
330b0 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
330c0 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
330d0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
330e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d   CAPI3REF: Autom
330f0 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74  atically Load St
33100 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20  atically Linked 
33110 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Extensions.**.**
33120 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
33130 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e 74   causes the xEnt
33140 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 69  ryPoint() functi
33150 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
33160 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77   for.** each new
33170 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33180 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 63  ction] that is c
33190 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 65  reated.  The ide
331a0 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a 2a  a here is that.*
331b0 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  * xEntryPoint() 
331c0 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  is the entry poi
331d0 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 61  nt for a statica
331e0 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74  lly linked SQLit
331f0 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74  e extension.** t
33200 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 74  hat is to be aut
33210 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65  omatically loade
33220 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64  d into all new d
33230 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33240 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  ons..**.** ^(Eve
33250 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 6e  n though the fun
33260 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20  ction prototype 
33270 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 72  shows that xEntr
33280 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a  yPoint() takes.*
33290 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61  * no arguments a
332a0 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 2c  nd returns void,
332b0 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
332c0 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
332d0 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 75  th three.** argu
332e0 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 74  ments and expect
332f0 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 65  s and integer re
33300 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 73  sult as if the s
33310 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 0a  ignature of the.
33320 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 77  ** entry point w
33330 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  here as follows:
33340 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
33350 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73  te><pre>.** &nbs
33360 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 6f  p;  int xEntryPo
33370 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  int(.** &nbsp;  
33380 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a    sqlite3 *db,.*
33390 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
333a0 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73  t char **pzErrMs
333b0 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  g,.** &nbsp;    
333c0 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
333d0 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
333e0 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62  s *pThunk.** &nb
333f0 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  sp;  );.** </pre
33400 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
33410 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 45  .**.** If the xE
33420 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e  ntryPoint routin
33430 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20  e encounters an 
33440 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64  error, it should
33450 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a   make *pzErrMsg.
33460 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ** point to an a
33470 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
33480 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 6e   message (obtain
33490 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
334a0 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20  _mprintf()]).** 
334b0 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 70  and return an ap
334c0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
334d0 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65   code].  ^SQLite
334e0 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a 70   ensures that *p
334f0 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55  zErrMsg.** is NU
33500 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  LL before callin
33510 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  g the xEntryPoin
33520 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  t().  ^SQLite wi
33530 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71  ll invoke.** [sq
33540 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
33550 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 72   *pzErrMsg after
33560 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
33570 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79  eturns.  ^If any
33580 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
33590 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  ) returns an err
335a0 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  or, the [sqlite3
335b0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
335c0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
335d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
335e0 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 61  n_v2()] call tha
335f0 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 78  t provoked the x
33600 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 6c  EntryPoint() wil
33610 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43  l fail..**.** ^C
33620 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 61  alling sqlite3_a
33630 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29  uto_extension(X)
33640 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 70   with an entry p
33650 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 61  oint X that is a
33660 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65  lready.** on the
33670 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 74   list of automat
33680 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 73  ic extensions is
33690 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
336a0 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69  p. ^No entry poi
336b0 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61  nt.** will be ca
336c0 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  lled more than o
336d0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 74  nce for each dat
336e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
336f0 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 2e   that is opened.
33700 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33710 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
33720 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
33730 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33740 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
33750 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
33760 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
33770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
33780 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
33790 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
337a0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
337b0 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20 61  rface disables a
337c0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ll automatic ext
337d0 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 73  ensions previous
337e0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
337f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33800 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
33810 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  ]..*/.void sqlit
33820 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
33830 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
33840 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
33850 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
33860 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
33870 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  sm is currently 
33880 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
33890 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
338a0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
338b0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
338c0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
338d0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
338e0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
338f0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
33900 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
33910 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
33920 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
33930 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
33940 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
33950 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
33960 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
33970 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
33980 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
33990 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
339a0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
339b0 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73  ** Structures us
339c0 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61  ed by the virtua
339d0 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
339e0 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  e.*/.typedef str
339f0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
33a00 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74   sqlite3_vtab;.t
33a10 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
33a20 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
33a30 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
33a40 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72  nfo;.typedef str
33a50 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
33a60 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f  _cursor sqlite3_
33a70 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70  vtab_cursor;.typ
33a80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
33a90 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74  te3_module sqlit
33aa0 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a  e3_module;../*.*
33ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
33ac0 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74  ual Table Object
33ad0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
33ae0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69  lite3_module {vi
33af0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
33b00 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  le}.**.** This s
33b10 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69  tructure, someti
33b20 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22  mes called a a "
33b30 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33b40 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e  dule", .** defin
33b50 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  es the implement
33b60 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74  ation of a [virt
33b70 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a  ual tables].  .*
33b80 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65  * This structure
33b90 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79   consists mostly
33ba0 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20   of methods for 
33bb0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
33bc0 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62  * ^A virtual tab
33bd0 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65  le module is cre
33be0 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20  ated by filling 
33bf0 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a  in a persistent.
33c00 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
33c10 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e  his structure an
33c20 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e  d passing a poin
33c30 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74  ter to that inst
33c40 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ance.** to [sqli
33c50 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
33c60 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
33c70 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
33c80 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  2()]..** ^The re
33c90 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69  gistration remai
33ca0 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69  ns valid until i
33cb0 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79  t is replaced by
33cc0 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20   a different.** 
33cd0 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20  module or until 
33ce0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33cf0 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73  nnection] closes
33d00 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  .  The content.*
33d10 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  * of this struct
33d20 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61  ure must not cha
33d30 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20  nge while it is 
33d40 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a  registered with.
33d50 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  ** any database 
33d60 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  connection..*/.s
33d70 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
33d80 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65  dule {.  int iVe
33d90 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
33da0 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a  Create)(sqlite3*
33db0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
33dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
33dd0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
33de0 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
33df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
33e00 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
33e10 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
33e20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28  int (*xConnect)(
33e30 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
33e40 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
33e50 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
33e60 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
33e70 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
33e80 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
33e90 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
33ea0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  r**);.  int (*xB
33eb0 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65  estIndex)(sqlite
33ec0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
33ed0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
33ee0 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69  o*);.  int (*xDi
33ef0 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  sconnect)(sqlite
33f00 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
33f10 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79    int (*xDestroy
33f20 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
33f30 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
33f40 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
33f50 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69  tab *pVTab, sqli
33f60 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
33f70 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69  **ppCursor);.  i
33f80 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
33f90 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
33fa0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  *);.  int (*xFil
33fb0 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ter)(sqlite3_vta
33fc0 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69  b_cursor*, int i
33fd0 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61  dxNum, const cha
33fe0 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20  r *idxStr,.     
33ff0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
34000 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  rgc, sqlite3_val
34010 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e  ue **argv);.  in
34020 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74  t (*xNext)(sqlit
34030 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
34040 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28  ;.  int (*xEof)(
34050 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34060 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
34070 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f  Column)(sqlite3_
34080 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
34090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
340a0 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
340b0 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74  owid)(sqlite3_vt
340c0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
340d0 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  te3_int64 *pRowi
340e0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64  d);.  int (*xUpd
340f0 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ate)(sqlite3_vta
34100 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  b *, int, sqlite
34110 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69  3_value **, sqli
34120 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20  te3_int64 *);.  
34130 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71  int (*xBegin)(sq
34140 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34150 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  b);.  int (*xSyn
34160 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  c)(sqlite3_vtab 
34170 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
34180 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65  *xCommit)(sqlite
34190 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
341a0 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63    int (*xRollbac
341b0 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  k)(sqlite3_vtab 
341c0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
341d0 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28  *xFindFunction)(
341e0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
341f0 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63  tab, int nArg, c
34200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
34210 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34220 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a           void (*
34230 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  *pxFunc)(sqlite3
34240 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
34250 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
34260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34270 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70         void **pp
34280 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  Arg);.  int (*xR
34290 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  ename)(sqlite3_v
342a0 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73  tab *pVtab, cons
342b0 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d  t char *zNew);.}
342c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
342d0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
342e0 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d   Indexing Inform
342f0 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44  ation.** KEYWORD
34300 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  S: sqlite3_index
34310 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20  _info.**.** The 
34320 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
34330 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  fo structure and
34340 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75 72   its substructur
34350 65 73 20 69 73 20 75 73 65 64 20 61 73 20 70 61  es is used as pa
34360 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  rt.** of the [vi
34370 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74  rtual table] int
34380 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73  erface to.** pas
34390 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
343a0 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
343b0 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
343c0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a  e [xBestIndex].*
343d0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76  * method of a [v
343e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
343f0 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64  ule].  The field
34400 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
34410 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
34420 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
34430 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
34440 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
34450 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
34460 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
34470 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
34480 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  elds..**.** ^(Th
34490 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
344a0 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
344b0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
344c0 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
344d0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  rm:.**.** <block
344e0 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20  quote>column OP 
344f0 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  expr</blockquote
34500 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50  >.**.** where OP
34510 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74   is =, &lt;, &lt
34520 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74  ;=, &gt;, or &gt
34530 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72  ;=.)^  ^(The par
34540 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72  ticular operator
34550 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e   is.** stored in
34560 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f   aConstraint[].o
34570 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  p using one of t
34580 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
34590 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
345a0 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  Q | SQLITE_INDEX
345b0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c  _CONSTRAINT_ val
345c0 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  ues].)^.** ^(The
345d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
345e0 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69  lumn is stored i
345f0 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74  n.** aConstraint
34600 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e  [].iColumn.)^  ^
34610 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75  (aConstraint[].u
34620 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
34630 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
34640 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
34650 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
34660 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
34670 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
34680 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
34690 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
346a0 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ot.)^.**.** ^The
346b0 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d   optimizer autom
346c0 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73  atically inverts
346d0 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f   terms of the fo
346e0 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75  rm "expr OP colu
346f0 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73  mn".** and makes
34700 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63   other simplific
34710 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48  ations to the WH
34720 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e  ERE clause in an
34730 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67   attempt to.** g
34740 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45  et as many WHERE
34750 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
34760 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77  to the form show
34770 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69  n above as possi
34780 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f  ble..** ^The aCo
34790 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
347a0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
347b0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
347c0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c   that are.** rel
347d0 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72  evant to the par
347e0 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20  ticular virtual 
347f0 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72  table being quer
34800 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f  ied..**.** ^Info
34810 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
34820 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
34830 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  e is stored in a
34840 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45  OrderBy[]..** ^E
34850 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64  ach term of aOrd
34860 65 72 42 79 20 72 65 63 6f 72 64 73 20 61 20 63  erBy records a c
34870 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44  olumn of the ORD
34880 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a  ER BY clause..**
34890 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e  .** The [xBestIn
348a0 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74  dex] method must
348b0 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e   fill aConstrain
348c0 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e  tUsage[] with in
348d0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
348e0 75 74 20 77 68 61 74 20 70 61 72 61 6d 65 74 65  ut what paramete
348f0 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46  rs to pass to xF
34900 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76  ilter.  ^If argv
34910 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20  Index>0 then.** 
34920 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
34930 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65  ide of the corre
34940 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72  sponding aConstr
34950 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61  aint[] is evalua
34960 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d  ted.** and becom
34970 65 73 20 74 68 65 20 61 72 67 76 49 6e 64 65 78  es the argvIndex
34980 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67  -th entry in arg
34990 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72  v.  ^(If aConstr
349a0 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74  aintUsage[].omit
349b0 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65  .** is true, the
349c0 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  n the constraint
349d0 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62   is assumed to b
349e0 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20  e fully handled 
349f0 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61  by the.** virtua
34a00 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e  l table and is n
34a10 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e  ot checked again
34a20 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a   by SQLite.)^.**
34a30 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20  .** ^The idxNum 
34a40 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65  and idxPtr value
34a50 73 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61  s are recorded a
34a60 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  nd passed into t
34a70 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20  he.** [xFilter] 
34a80 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c  method..** ^[sql
34a90 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
34aa0 75 73 65 64 20 74 6f 20 66 72 65 65 20 69 64 78  used to free idx
34ab0 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  Ptr if and only 
34ac0 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65  if.** needToFree
34ad0 49 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a  IdxPtr is true..
34ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72  **.** ^The order
34af0 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73  ByConsumed means
34b00 20 74 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f   that output fro
34b10 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65  m [xFilter]/[xNe
34b20 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69  xt] will occur i
34b30 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74  n.** the correct
34b40 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69 73 66   order to satisf
34b50 79 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  y the ORDER BY c
34b60 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f  lause so that no
34b70 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72   separate.** sor
34b80 74 69 6e 67 20 73 74 65 70 20 69 73 20 72 65 71  ting step is req
34b90 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
34ba0 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
34bb0 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69  value is an esti
34bc0 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74  mate of the cost
34bd0 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a   of doing the.**
34be0 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b   particular look
34bf0 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e  up.  A full scan
34c00 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69 74 68   of a table with
34c10 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
34c20 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74  d have.** a cost
34c30 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79   of N.  A binary
34c40 20 73 65 61 72 63 68 20 6f 66 20 61 20 74 61 62   search of a tab
34c50 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20  le of N entries 
34c60 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a  should have a.**
34c70 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69   cost of approxi
34c80 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a  mately log(N)..*
34c90 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
34ca0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20  _index_info {.  
34cb0 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69  /* Inputs */.  i
34cc0 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
34cd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
34ce0 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69  ber of entries i
34cf0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  n aConstraint */
34d00 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
34d10 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
34d20 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
34d30 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
34d40 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e      /* Column on
34d50 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
34d60 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  of constraint */
34d70 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
34d80 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20  har op;         
34d90 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70  /* Constraint op
34da0 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75  erator */.     u
34db0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75 73 61  nsigned char usa
34dc0 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65  ble;     /* True
34dd0 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61   if this constra
34de0 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f  int is usable */
34df0 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f  .     int iTermO
34e00 66 66 73 65 74 3b 20 20 20 20 20 20 20 20 20 20  ffset;          
34e10 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c  /* Used internal
34e20 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20  ly - xBestIndex 
34e30 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f  should ignore */
34e40 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
34e50 74 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  t;            /*
34e60 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20   Table of WHERE 
34e70 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
34e80 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64  ts */.  int nOrd
34e90 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20  erBy;           
34ea0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
34eb0 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44  terms in the ORD
34ec0 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
34ed0 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33    struct sqlite3
34ee0 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b  _index_orderby {
34ef0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
34f00 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
34f10 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  /* Column number
34f20 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
34f30 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20 20  d char desc;    
34f40 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44     /* True for D
34f50 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20  ESC.  False for 
34f60 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72  ASC. */.  } *aOr
34f70 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20 20  derBy;          
34f80 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45       /* The ORDE
34f90 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20  R BY clause */. 
34fa0 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20   /* Outputs */. 
34fb0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
34fc0 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
34fd0 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74  _usage {.    int
34fe0 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20   argvIndex;     
34ff0 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20        /* if >0, 
35000 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61  constraint is pa
35010 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46  rt of argv to xF
35020 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73  ilter */.    uns
35030 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b  igned char omit;
35040 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20        /* Do not 
35050 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f 72 20  code a test for 
35060 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
35070 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
35080 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20  intUsage;.  int 
35090 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20  idxNum;         
350a0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
350b0 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66   used to identif
350c0 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20  y the index */. 
350d0 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20   char *idxStr;  
350e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
350f0 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20  tring, possibly 
35100 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
35110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a  lite3_malloc */.
35120 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65    int needToFree
35130 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20  IdxStr;      /* 
35140 46 72 65 65 20 69 64 78 53 74 72 20 75 73 69 6e  Free idxStr usin
35150 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
35160 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e   if true */.  in
35170 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  t orderByConsume
35180 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65  d;       /* True
35190 20 69 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c   if output is al
351a0 72 65 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f  ready ordered */
351b0 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61  .  double estima
351c0 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a  tedCost;      /*
351d0 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20   Estimated cost 
351e0 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e  of using this in
351f0 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  dex */.};../*.**
35200 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
35210 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74 72 61  al Table Constra
35220 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43 6f 64  int Operator Cod
35230 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  es.**.** These m
35240 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20 74 68  acros defined th
35250 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  e allowed values
35260 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   for the.** [sql
35270 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d  ite3_index_info]
35280 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f  .aConstraint[].o
35290 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68 20 76  p field.  Each v
352a0 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74 73 0a  alue represents.
352b0 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72 20 74  ** an operator t
352c0 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
352d0 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65 72 6d   constraint term
352e0 20 69 6e 20 74 68 65 20 77 48 45 52 45 20 63 6c   in the wHERE cl
352f0 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65  ause of.** a que
35300 72 79 20 74 68 61 74 20 75 73 65 73 20 61 20 5b  ry that uses a [
35310 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
35320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
35330 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
35340 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
35350 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
35360 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
35370 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
35380 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
35390 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
353a0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
353b0 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
353c0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
353d0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
353e0 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
353f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
35400 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
35410 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
35420 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
35430 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
35440 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  Implementation.*
35450 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
35460 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
35470 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
35480 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
35490 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20  odule] name..** 
354a0 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75  ^Module names mu
354b0 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
354c0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74   before.** creat
354d0 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ing a new [virtu
354e0 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20  al table] using 
354f0 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62  the module and b
35500 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a  efore using a.**
35510 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69   preexisting [vi
35520 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72  rtual table] for
35530 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
35540 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e  ** ^The module n
35550 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ame is registere
35560 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  d on the [databa
35570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
35580 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
35590 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
355a0 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f  er.  ^The name o
355b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20  f the module is 
355c0 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a  given by the .**
355d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
355e0 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  r.  ^The third p
355f0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
35600 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  inter to.** the 
35610 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
35620 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
35630 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20  able module].   
35640 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70  ^The fourth.** p
35650 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
35660 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20  rbitrary client 
35670 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
35680 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
35690 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ugh.** into the 
356a0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
356b0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
356c0 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
356d0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20  table module.** 
356e0 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75  when a new virtu
356f0 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62  al table is be b
35700 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20  eing created or 
35710 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a  reinitialized..*
35720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35730 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
35740 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68  v2() interface h
35750 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d  as a fifth param
35760 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
35770 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
35780 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
35790 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20  he pClientData. 
357a0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a   ^SQLite will.**
357b0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
357c0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
357d0 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  (if it is not NU
357e0 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a  LL) when SQLite.
357f0 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  ** no longer nee
35800 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  ds the pClientDa
35810 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  ta pointer.  ^Th
35820 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
35830 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69 6e 76  l also.** be inv
35840 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
35850 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
35860 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 66  te_module_v2() f
35870 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ails..** ^The sq
35880 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
35890 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ule().** interfa
358a0 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
358b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
358c0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77  te_module_v2() w
358d0 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65  ith a NULL.** de
358e0 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74  structor..*/.int
358f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35900 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65  module(.  sqlite
35910 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
35920 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63       /* SQLite c
35930 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67  onnection to reg
35940 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74  ister module wit
35950 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  h */.  const cha
35960 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20  r *zName,       
35970 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
35980 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e   module */.  con
35990 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  st sqlite3_modul
359a0 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f  e *p,   /* Metho
359b0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
359c0 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c  e */.  void *pCl
359d0 69 65 6e 74 44 61 74 61 20 20 20 20 20 20 20 20  ientData        
359e0 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
359f0 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f   for xCreate/xCo
35a00 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20  nnect */.);.int 
35a10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
35a20 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69  odule_v2(.  sqli
35a30 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35a40 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
35a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
35a60 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
35a70 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
35a80 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
35a90 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
35aa0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
35ab0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
35ac0 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
35ad0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
35ae0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
35af0 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20  ClientData,     
35b00 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
35b10 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
35b20 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69  Connect */.  voi
35b30 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
35b40 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c  d*)     /* Modul
35b50 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
35b60 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ction */.);../*.
35b70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
35b80 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61  tual Table Insta
35b90 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  nce Object.** KE
35ba0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
35bb0 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  vtab.**.** Every
35bc0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
35bd0 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
35be0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
35bf0 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69  bclass.** of thi
35c00 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63  s object to desc
35c10 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
35c20 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
35c30 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
35c40 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
35c50 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
35c60 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
35c70 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
35c80 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
35c90 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
35ca0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
35cb0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
35cc0 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
35cd0 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
35ce0 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
35cf0 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
35d00 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
35d10 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c  ** ^Virtual tabl
35d20 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
35d30 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
35d40 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
35d50 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
35d60 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
35d70 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
35d80 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
35d90 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
35da0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
35db0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
35dc0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
35dd0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
35de0 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
35df0 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
35e00 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
35e10 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74  rrMsg.  ^After t
35e20 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35e30 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
35e40 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
35e50 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
35e60 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
35e70 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
35e80 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
35e90 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
35ea0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
35eb0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
35ec0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
35ed0 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
35ee0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
35ef0 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
35f00 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
35f10 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
35f20 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
35f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35f40 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
35f50 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
35f60 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
35f70 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
35f80 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
35f90 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
35fa0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
35fb0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
35fc0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
35fd0 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
35fe0 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
35ff0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
36000 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
36010 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
36020 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
36030 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
36040 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62  sor {virtual tab
36050 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a  le cursor}.**.**
36060 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
36070 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
36080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
36090 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
360a0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
360b0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
360c0 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
360d0 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
360e0 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  he.** [virtual t
360f0 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73  able] and are us
36100 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
36110 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
36120 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
36130 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
36140 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
36150 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e  te3_module.xOpen
36160 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64   | xOpen] method
36170 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61   of the module a
36180 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  nd are destroyed
36190 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69  .** by the [sqli
361a0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73  te3_module.xClos
361b0 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68  e | xClose] meth
361c0 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  od.  Cursors are
361d0 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
361e0 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78  [xFilter], [xNex
361f0 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f  t], [xEof], [xCo
36200 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77  lumn], and [xRow
36210 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  id] methods.** o
36220 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
36230 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
36240 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
36250 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
36260 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
36270 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
36280 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
36290 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
362a0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
362b0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
362c0 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
362d0 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
362e0 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
362f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36300 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
36310 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
36320 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
36330 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
36340 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
36350 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
36360 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
36370 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
36380 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
36390 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
363a0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
363b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
363c0 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65  Declare The Sche
363d0 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20  ma Of A Virtual 
363e0 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Table.**.** ^The
363f0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
36400 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
36410 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75  s of a.** [virtu
36420 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
36430 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72   call this inter
36440 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61  face.** to decla
36450 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74  re the format (t
36460 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74  he names and dat
36470 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f  atypes of the co
36480 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65  lumns) of.** the
36490 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
364a0 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a  they implement..
364b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
364c0 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69  eclare_vtab(sqli
364d0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
364e0 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20   *zSQL);../*.** 
364f0 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f  CAPI3REF: Overlo
36500 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f  ad A Function Fo
36510 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
36520 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61  e.**.** ^(Virtua
36530 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f  l tables can pro
36540 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65  vide alternative
36550 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36560 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
36570 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e   using the [xFin
36580 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f  dFunction] metho
36590 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  d of the [virtua
365a0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
365b0 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c    .** But global
365c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f   versions of tho
365d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  se functions.** 
365e0 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72  must exist in or
365f0 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f  der to be overlo
36600 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  aded.)^.**.** ^(
36610 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73  This API makes s
36620 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72  ure a global ver
36630 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69  sion of a functi
36640 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63  on with a partic
36650 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64  ular.** name and
36660 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
36670 65 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49  eters exists.  I
36680 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69  f no such functi
36690 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66  on exists.** bef
366a0 6f 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20  ore this API is 
366b0 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75  called, a new fu
366c0 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  nction is create
366d0 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65  d.)^  ^The imple
366e0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  mentation.** of 
366f0 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e  the new function
36700 20 61 6c 77 61 79 73 20 63 61 75 73 65 73 20 61   always causes a
36710 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f 20 62  n exception to b
36720 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a  e thrown.  So.**
36730 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69 6f   the new functio
36740 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f  n is not good fo
36750 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20 69 74  r anything by it
36760 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a  self.  Its only.
36770 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20 74 6f  ** purpose is to
36780 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c 64 65   be a placeholde
36790 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  r function that 
367a0 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  can be overloade
367b0 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72 74 75  d.** by a [virtu
367c0 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e  al table]..*/.in
367d0 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
367e0 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
367f0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
36800 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
36810 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
36820 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
36830 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
36840 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
36850 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
36860 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
36870 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
36880 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
36890 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
368a0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
368b0 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
368c0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
368d0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
368e0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
368f0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
36900 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
36910 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
36920 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
36930 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
36940 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
36950 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
36960 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
36970 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
36980 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
36990 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
369a0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
369b0 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
369c0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
369d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48  ** CAPI3REF: A H
369e0 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e  andle To An Open
369f0 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44   BLOB.** KEYWORD
36a00 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d  S: {BLOB handle}
36a10 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a   {BLOB handles}.
36a20 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
36a30 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
36a40 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f   represents an o
36a50 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63  pen BLOB on whic
36a60 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  h.** [sqlite3_bl
36a70 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
36a80 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
36a90 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
36aa0 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66  ..** ^Objects of
36ab0 20 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63   this type are c
36ac0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
36ad0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a  e3_blob_open()].
36ae0 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64  ** and destroyed
36af0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
36b00 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e  b_close()]..** ^
36b10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
36b20 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
36b30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
36b40 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  e()] interfaces.
36b50 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
36b60 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
36b70 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e  small subsection
36b80 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a  s of the BLOB..*
36b90 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
36ba0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
36bb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36bc0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
36bd0 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a  BLOB in bytes..*
36be0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
36bf0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71   sqlite3_blob sq
36c00 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a  lite3_blob;../*.
36c10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
36c20 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63  n A BLOB For Inc
36c30 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a  remental I/O.**.
36c40 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
36c50 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c  aces opens a [BL
36c60 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64  OB handle | hand
36c70 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  le] to the BLOB 
36c80 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f  located.** in ro
36c90 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a  w iRow, column z
36ca0 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54  Column, table zT
36cb0 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65  able in database
36cc0 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65   zDb;.** in othe
36cd0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d  r words, the sam
36ce0 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c  e BLOB that woul
36cf0 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79  d be selected by
36d00 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a  :.**.** <pre>.**
36d10 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c       SELECT zCol
36d20 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61  umn FROM zDb.zTa
36d30 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64  ble WHERE [rowid
36d40 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70  ] = iRow;.** </p
36d50 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  re>)^.**.** ^If 
36d60 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
36d70 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  ter is non-zero,
36d80 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   then the BLOB i
36d90 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
36da0 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61  d.** and write a
36db0 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73  ccess. ^If it is
36dc0 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20   zero, the BLOB 
36dd0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
36de0 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  ad access..** ^I
36df0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
36e00 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
36e10 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
36e20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70  of an index or p
36e30 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66  rimary .** key f
36e40 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20  or writing. ^If 
36e50 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
36e60 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e  straints] are en
36e70 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a  abled, it is .**
36e80 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
36e90 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74   open a column t
36ea0 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
36eb0 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72   [child key] for
36ec0 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   writing..**.** 
36ed0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64  ^Note that the d
36ee0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
36ef0 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  not the filename
36f00 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a   that contains.*
36f10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  * the database b
36f20 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79  ut rather the sy
36f30 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74  mbolic name of t
36f40 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  he database that
36f50 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65  .** appears afte
36f60 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64  r the AS keyword
36f70 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
36f80 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20  se is connected 
36f90 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a  using [ATTACH]..
36fa0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e  ** ^For the main
36fb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
36fc0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
36fd0 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20  e is "main"..** 
36fe0 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73  ^For TEMP tables
36ff0 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
37000 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a  ame is "temp"..*
37010 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73  *.** ^(On succes
37020 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
37030 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74  s returned and t
37040 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e  he new [BLOB han
37050 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a  dle] is written.
37060 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f  ** to *ppBlob. O
37070 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
37080 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
37090 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62  rned and *ppBlob
370a0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65   is set.** to be
370b0 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e   a null pointer.
370c0 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  )^.** ^This func
370d0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64  tion sets the [d
370e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
370f0 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  on] error code a
37100 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63  nd message.** ac
37110 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71  cessible via [sq
37120 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37130 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
37140 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61  rmsg()] and rela
37150 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ted.** functions
37160 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  . ^Note that the
37170 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c   *ppBlob variabl
37180 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74  e is always init
37190 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20  ialized in a.** 
371a0 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69  way that makes i
371b0 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65  t safe to invoke
371c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
371d0 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c  lose()] on *ppBl
371e0 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ob.** regardless
371f0 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20   of the success 
37200 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
37210 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
37220 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74  * ^(If the row t
37230 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c  hat a BLOB handl
37240 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d  e points to is m
37250 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a  odified by an.**
37260 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45   [UPDATE], [DELE
37270 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43  TE], or by [ON C
37280 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66  ONFLICT] side-ef
37290 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68  fects.** then th
372a0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
372b0 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69   marked as "expi
372c0 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73  red"..** This is
372d0 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c   true if any col
372e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69  umn of the row i
372f0 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  s changed, even 
37300 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65  a column.** othe
37310 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74  r than the one t
37320 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
37330 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20  s open on.)^.** 
37340 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74  ^Calls to [sqlit
37350 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
37360 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
37370 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a  b_write()] for.*
37380 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42  * a expired BLOB
37390 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74   handle fail wit
373a0 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65  h an return code
373b0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
373c0 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73  T]..** ^(Changes
373d0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20   written into a 
373e0 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68  BLOB prior to th
373f0 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20  e BLOB expiring 
37400 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65  are not.** rolle
37410 64 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78  d back by the ex
37420 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  piration of the 
37430 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e  BLOB.  Such chan
37440 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ges will eventua
37450 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66  lly.** commit if
37460 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
37470 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
37480 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  mpletion.)^.**.*
37490 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69  * ^Use the [sqli
374a0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
374b0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64  ] interface to d
374c0 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a  etermine the siz
374d0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  e of.** the open
374e0 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73  ed blob.  ^The s
374f0 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61  ize of a blob ma
37500 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  y not be changed
37510 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65   by this.** inte
37520 72 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20  rface.  Use the 
37530 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d  [UPDATE] SQL com
37540 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74  mand to change t
37550 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20  he size of a.** 
37560 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  blob..**.** ^The
37570 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
37580 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b  eroblob()] and [
37590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
375a0 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72  eroblob()] inter
375b0 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65  faces.** and the
375c0 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62   built-in [zerob
375d0 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f  lob] SQL functio
375e0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69  n can be used, i
375f0 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f  f desired,.** to
37600 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79   create an empty
37610 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c  , zero-filled bl
37620 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72  ob in which to r
37630 65 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69  ead or write usi
37640 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  ng.** this inter
37650 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  face..**.** To a
37660 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20  void a resource 
37670 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e  leak, every open
37680 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73   [BLOB handle] s
37690 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79  hould eventually
376a0 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20  .** be released 
376b0 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
376c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
376d0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
376e0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20  te3_blob_open(. 
376f0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e   sqlite3*,.  con
37700 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20  st char *zDb,.  
37710 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
37720 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  le,.  const char
37730 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c   *zColumn,.  sql
37740 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c  ite3_int64 iRow,
37750 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20  .  int flags,.  
37760 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70  sqlite3_blob **p
37770 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  pBlob.);../*.** 
37780 43 41 50 49 33 52 45 46 3a 20 4d 6f 76 65 20 61  CAPI3REF: Move a
37790 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74 6f 20   BLOB Handle to 
377a0 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a 2a 20  a New Row.**.** 
377b0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  ^This function i
377c0 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65 20 61  s used to move a
377d0 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f 62 20  n existing blob 
377e0 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74 20 69  handle so that i
377f0 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  t points.** to a
37800 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77 20 6f   different row o
37810 66 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  f the same datab
37820 61 73 65 20 74 61 62 6c 65 2e 20 5e 54 68 65 20  ase table. ^The 
37830 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e 74  new row is ident
37840 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
37850 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73 73  rowid value pass
37860 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
37870 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79 20   argument. Only 
37880 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a  the row can be.*
37890 2a 20 63 68 61 6e 67 65 64 2e 20 5e 54 68 65 20  * changed. ^The 
378a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20  database, table 
378b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68  and column on wh
378c0 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61 6e  ich the blob han
378d0 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20 72  dle is open.** r
378e0 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e 20  emain the same. 
378f0 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74 69  Moving an existi
37900 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 74  ng blob handle t
37910 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e 20  o a new row can 
37920 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61  be.** faster tha
37930 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65 78  n closing the ex
37940 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61 6e  isting handle an
37950 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77 20  d opening a new 
37960 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  one..**.** ^(The
37970 20 6e 65 77 20 72 6f 77 20 6d 75 73 74 20 6d 65   new row must me
37980 65 74 20 74 68 65 20 73 61 6d 65 20 63 72 69 74  et the same crit
37990 65 72 69 61 20 61 73 20 66 6f 72 20 5b 73 71 6c  eria as for [sql
379a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
379b0 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74 20 65  ] -.** it must e
379c0 78 69 73 74 20 61 6e 64 20 74 68 65 72 65 20 6d  xist and there m
379d0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
379e0 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c  blob or text val
379f0 75 65 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  ue stored in.** 
37a00 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 63 6f  the nominated co
37a10 6c 75 6d 6e 2e 29 5e 20 5e 49 66 20 74 68 65 20  lumn.)^ ^If the 
37a20 6e 65 77 20 72 6f 77 20 69 73 20 6e 6f 74 20 70  new row is not p
37a30 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20 74 61  resent in the ta
37a40 62 6c 65 2c 20 6f 72 20 69 66 0a 2a 2a 20 69 74  ble, or if.** it
37a50 20 64 6f 65 73 20 6e 6f 74 20 63 6f 6e 74 61 69   does not contai
37a60 6e 20 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 74  n a blob or text
37a70 20 76 61 6c 75 65 2c 20 6f 72 20 69 66 20 61 6e   value, or if an
37a80 6f 74 68 65 72 20 65 72 72 6f 72 20 6f 63 63 75  other error occu
37a90 72 73 2c 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65  rs, an.** SQLite
37aa0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
37ab0 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
37ac0 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73 20 63  blob handle is c
37ad0 6f 6e 73 69 64 65 72 65 64 20 61 62 6f 72 74 65  onsidered aborte
37ae0 64 2e 0a 2a 2a 20 5e 41 6c 6c 20 73 75 62 73 65  d..** ^All subse
37af0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
37b00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
37b10 64 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62  d()], [sqlite3_b
37b20 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 6f 72 0a  lob_write()] or.
37b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
37b40 5f 72 65 6f 70 65 6e 28 29 5d 20 6f 6e 20 61 6e  _reopen()] on an
37b50 20 61 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61   aborted blob ha
37b60 6e 64 6c 65 20 69 6d 6d 65 64 69 61 74 65 6c 79  ndle immediately
37b70 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
37b80 45 5f 41 42 4f 52 54 2e 20 5e 43 61 6c 6c 69 6e  E_ABORT. ^Callin
37b90 67 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  g [sqlite3_blob_
37ba0 62 79 74 65 73 28 29 5d 20 6f 6e 20 61 6e 20 61  bytes()] on an a
37bb0 62 6f 72 74 65 64 20 62 6c 6f 62 20 68 61 6e 64  borted blob hand
37bc0 6c 65 0a 2a 2a 20 61 6c 77 61 79 73 20 72 65 74  le.** always ret
37bd0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
37be0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
37bf0 73 65 74 73 20 74 68 65 20 64 61 74 61 62 61 73  sets the databas
37c00 65 20 68 61 6e 64 6c 65 20 65 72 72 6f 72 20 63  e handle error c
37c10 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 2e  ode and message.
37c20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
37c30 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
37c40 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65 6e 28  te3_blob_reopen(
37c50 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
37c60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37c80 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
37c90 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
37ca0 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
37cb0 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
37cc0 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
37cd0 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
37ce0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
37cf0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
37d00 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
37d10 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
37d20 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
37d30 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
37d40 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
37d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
37d60 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
37d70 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
37d80 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
37d90 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
37da0 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
37db0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
37dc0 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
37dd0 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
37de0 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
37df0 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
37e00 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
37e10 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
37e20 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
37e30 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
37e40 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
37e50 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
37e60 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
37e70 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
37e80 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
37e90 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
37ea0 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
37eb0 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
37ec0 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
37ed0 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
37ee0 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
37ef0 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
37f00 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
37f10 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
37f20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
37f30 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
37f40 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
37f50 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
37f60 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
37f70 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
37f80 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
37f90 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
37fa0 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
37fb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37fc0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
37fd0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
37fe0 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
37ff0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
38000 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
38010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38020 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
38030 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
38040 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
38050 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
38060 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
38070 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
38080 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
38090 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
380a0 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
380b0 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
380c0 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
380d0 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
380e0 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
380f0 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
38100 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
38110 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
38120 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
38130 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
38140 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
38150 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
38160 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
38170 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
38180 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
38190 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
381a0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
381b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
381c0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
381d0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
381e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
381f0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
38200 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
38210 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
38220 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
38230 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
38240 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
38250 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
38260 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
38270 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
38280 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
38290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
382a0 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
382b0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
382c0 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
382d0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
382e0 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
382f0 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
38300 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
38310 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
38320 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
38330 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
38340 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
38350 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
38360 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
38370 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
38380 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
38390 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
383a0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
383b0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
383c0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
383d0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
383e0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
383f0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
38400 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
38410 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
38420 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
38430 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
38440 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
38450 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
38460 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
38470 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
38480 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
38490 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
384a0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
384b0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
384c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
384d0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
384e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
384f0 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
38500 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
38510 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
38520 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
38530 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
38540 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
38550 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
38560 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
38570 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
38580 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
38590 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
385a0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
385b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
385c0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
385d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
385e0 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
385f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
38600 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
38610 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
38620 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
38630 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
38640 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
38650 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
38660 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
38670 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
38680 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
38690 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
386a0 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
386b0 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
386c0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
386d0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
386e0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
386f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
38700 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
38710 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
38720 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
38730 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
38740 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
38750 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
38760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38770 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
38780 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
38790 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
387a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
387b0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
387c0 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
387d0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
387e0 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
387f0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
38800 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
38810 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
38820 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
38830 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
38840 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
38850 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
38860 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
38870 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
38880 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
38890 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
388a0 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
388b0 72 69 74 69 6e 67 20 28 74 68 65 20