/ Hex Artifact Content
Login

Artifact 7afbe9fb794092cb38bd3cfab72c39560ce0def5:


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 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
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: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly 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 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 73  _vfs*, sqlite3_s
9670: 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65  hm*, int reqSize
9680: 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29  , int *pNewSize)
9690: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65  ;.  int (*xShmGe
96a0: 74 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  t)(sqlite3_vfs*,
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20 69   sqlite3_shm*, i
96c0: 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74 20  nt reqSize, int 
96d0: 2a 70 53 69 7a 65 2c 20 76 6f 69 64 2a 2a 29 3b  *pSize, void**);
96e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 52 65 6c  .  int (*xShmRel
96f0: 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  ease)(sqlite3_vf
9700: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a  s*, sqlite3_shm*
9710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
9720: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ock)(sqlite3_vfs
9730: 2a 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c  *, sqlite3_shm*,
9740: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
9750: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
9760: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f  .  int (*xShmClo
9770: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9780: 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20  , sqlite3_shm*, 
9790: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
97a0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
97b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
97c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 6c 64  const char *zOld
97d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
97e0: 65 77 2c 20 69 6e 74 20 64 69 72 53 79 6e 63 29  ew, int dirSync)
97f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
9800: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
9810: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
9820: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
9830: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
9840: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
9850: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
9860: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
9870: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
9880: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
9890: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
98a0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
98b0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
98c0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
98d0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
98e0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
98f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
9900: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
9910: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
9920: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
9930: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9940: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
9950: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
9960: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
9970: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9980: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
9990: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
99a0: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
99b0: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
99c0: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
99d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
99e0: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
99f0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
9a00: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
9a10: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9a20: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
9a30: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9a40: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
9a50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9a60: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
9a70: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
9a80: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9a90: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
9aa0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9ab0: 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  able..** With SQ
9ac0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9ad0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9ae0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
9af0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9b00: 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a  is readable..*/.
9b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9b20: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
9b30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9b40: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b50: 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  E 1.#define SQLI
9b60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
9b70: 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      2../*.** CAP
9b80: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
9b90: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
9ba0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
9bb0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
9bc0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
9bd0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
9be0: 67 20 73 74 61 74 65 73 20 74 68 61 74 0a 2a 2a  g states that.**
9bf0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 68 6d 20   an sqlite3_shm 
9c00: 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 69 6e  object can be in
9c10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 48  .  The SQLITE_SH
9c20: 4d 5f 51 55 45 52 59 20 69 6e 74 65 67 65 72 0a  M_QUERY integer.
9c30: 2a 2a 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  ** is not a vali
9c40: 64 20 64 61 74 61 20 2d 20 69 74 20 69 73 20 61  d data - it is a
9c50: 20 63 6f 6e 73 74 61 6e 74 20 70 61 73 74 65 64   constant pasted
9c60: 20 74 6f 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   to the .** sqli
9c70: 74 65 33 5f 76 66 73 2e 78 53 68 6d 4c 6f 63 6b  te3_vfs.xShmLock
9c80: 28 29 20 6d 65 74 68 6f 64 20 66 6f 72 20 71 75  () method for qu
9c90: 65 72 79 69 6e 67 20 74 68 65 20 63 75 72 72 65  erying the curre
9ca0: 6e 74 20 6c 6f 63 6b 0a 2a 2a 20 73 74 61 74 65  nt lock.** state
9cb0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9cc0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
9cd0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
9ce0: 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44 20 20  QLITE_SHM_READ  
9cf0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9d00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44   SQLITE_SHM_READ
9d10: 5f 46 55 4c 4c 20 20 20 20 32 0a 23 64 65 66 69  _FULL    2.#defi
9d20: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 57 52  ne SQLITE_SHM_WR
9d30: 49 54 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  ITE        3.#de
9d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9d50: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 34 0a 23  PENDING      4.#
9d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9d70: 4d 5f 43 48 45 43 4b 50 4f 49 4e 54 20 20 20 35  M_CHECKPOINT   5
9d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d90: 53 48 4d 5f 52 45 43 4f 56 45 52 20 20 20 20 20  SHM_RECOVER     
9da0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
9db0: 45 5f 53 48 4d 5f 51 55 45 52 59 20 20 20 20 20  E_SHM_QUERY     
9dc0: 20 20 20 28 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43     (-1)../*.** C
9dd0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
9de0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
9df0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
9e00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9e10: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9e20: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
9e30: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
9e40: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
9e50: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
9e60: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
9e70: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
9e80: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
9e90: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
9ea0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
9eb0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
9ec0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
9ed0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
9ee0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
9ef0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
9f00: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
9f10: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
9f20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
9f30: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
9f40: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
9f50: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
9f60: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
9f70: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
9f80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
9f90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
9fa0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
9fb0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
9fc0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
9fd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9fe0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
9ff0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
a000: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
a010: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
a020: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
a030: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a040: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
a050: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
a060: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
a070: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
a080: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
a090: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
a0a0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
a0b0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
a0c0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
a0d0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
a0e0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
a0f0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
a100: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a110: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
a120: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
a130: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
a140: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
a150: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
a160: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
a170: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a180: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
a190: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
a1a0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a1b0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
a1c0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
a1d0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
a1e0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
a1f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
a200: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
a210: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
a220: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a230: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
a240: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
a250: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
a260: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
a270: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
a280: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
a290: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
a2a0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
a2b0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
a2c0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
a2d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
a2e0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
a2f0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
a300: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
a310: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
a320: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
a330: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
a340: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
a350: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
a360: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
a370: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
a380: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
a390: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a3a0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
a3b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
a3c0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
a3d0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
a3e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a3f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a400: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
a410: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
a420: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
a430: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
a440: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a450: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
a460: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
a470: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
a480: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
a490: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
a4a0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
a4b0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
a4c0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
a4d0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
a4e0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
a4f0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
a500: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a510: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a520: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
a530: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
a540: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
a550: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
a560: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
a570: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
a580: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
a590: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a5a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
a5b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
a5c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
a5d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
a5e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
a5f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a600: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
a610: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
a620: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
a630: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
a640: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
a650: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
a660: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
a670: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
a680: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a690: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
a6a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
a6b0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
a6c0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
a6d0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
a6e0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
a6f0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
a700: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
a710: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
a720: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
a730: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
a740: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
a750: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a760: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a770: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
a780: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
a790: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
a7a0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
a7b0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
a7c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
a7d0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
a7e0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
a7f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a800: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a810: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
a820: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
a830: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
a840: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
a850: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
a860: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
a870: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
a880: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
a890: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
a8a0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
a8b0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
a8c0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
a8d0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
a8e0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
a8f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a900: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
a910: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
a920: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
a930: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
a940: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
a950: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
a960: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
a970: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
a980: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
a990: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
a9a0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
a9b0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
a9c0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
a9d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
a9e0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
a9f0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
aa00: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
aa10: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
aa20: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
aa30: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
aa40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
aa50: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
aa60: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
aa70: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
aa80: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
aa90: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
aaa0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
aab0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
aac0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
aad0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
aae0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
aaf0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
ab00: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
ab10: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
ab20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
ab30: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
ab40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
ab50: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
ab60: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
ab70: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
ab80: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
ab90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
aba0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
abb0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
abc0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
abd0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
abe0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
abf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
ac00: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
ac10: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
ac20: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
ac30: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
ac40: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
ac50: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
ac60: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
ac70: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
ac80: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
ac90: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
aca0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
acb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
acc0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
acd0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
ace0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
acf0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
ad00: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
ad10: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
ad20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
ad30: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
ad40: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
ad50: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
ad60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ad70: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
ad80: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
ad90: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
ada0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
adb0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
adc0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
add0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
ade0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
adf0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
ae00: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
ae10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ae20: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
ae30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
ae40: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
ae50: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
ae60: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
ae70: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
ae80: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
ae90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
aea0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
aeb0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
aec0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
aed0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
aee0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
aef0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
af00: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
af10: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
af20: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
af30: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
af40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
af50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
af60: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
af70: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
af80: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
af90: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
afa0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
afb0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
afc0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
afd0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
afe0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
aff0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b000: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
b010: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
b020: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
b030: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
b040: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
b050: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
b060: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
b070: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
b080: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
b090: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
b0a0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
b0b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b0c0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
b0d0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
b0e0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
b0f0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
b100: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
b110: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
b120: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
b130: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b140: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
b150: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
b160: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
b170: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b180: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
b190: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
b1a0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
b1b0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
b1c0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
b1d0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
b1e0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b1f0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
b200: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
b210: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b220: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
b230: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
b240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
b250: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
b260: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
b270: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
b280: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
b290: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
b2a0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
b2b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
b2c0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
b2d0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
b2e0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
b2f0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
b300: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
b310: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
b320: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
b330: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
b340: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
b350: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b360: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
b370: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
b380: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
b390: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
b3a0: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
b3b0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
b3c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
b3d0: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
b3e0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
b3f0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
b400: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
b410: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
b420: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
b430: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
b440: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
b450: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
b460: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
b470: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
b480: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
b490: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
b4a0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
b4b0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
b4c0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
b4d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
b4e0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
b4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b500: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
b510: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
b520: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
b530: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
b540: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
b550: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
b560: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
b570: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
b580: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
b590: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
b5a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
b5b0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
b5c0: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
b5d0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
b5e0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
b5f0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
b600: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
b610: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
b620: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
b630: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
b640: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
b650: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
b660: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
b670: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
b680: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
b690: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
b6a0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
b6b0: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
b6c0: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
b6d0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
b6e0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
b6f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
b700: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
b710: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
b720: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
b730: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
b740: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
b750: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
b760: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
b770: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
b780: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
b790: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
b7a0: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
b7b0: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
b7c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
b7d0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
b7e0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
b7f0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
b800: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
b810: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
b820: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
b830: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
b840: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
b850: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
b860: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
b870: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
b880: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
b890: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b8a0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b8b0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b8c0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b8d0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b8e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b8f0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b900: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b910: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b920: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b930: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b940: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b950: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b960: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b970: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b980: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b990: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b9a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b9b0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b9c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
b9d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
b9e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
b9f0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
ba00: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ba10: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
ba20: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
ba30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
ba40: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ba50: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
ba60: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
ba70: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
ba80: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
ba90: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
baa0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bab0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
bac0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
bad0: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
bae0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
baf0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
bb00: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
bb10: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
bb20: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
bb30: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
bb40: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
bb50: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
bb60: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
bb70: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
bb80: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
bb90: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
bba0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
bbb0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
bbc0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
bbd0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
bbe0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
bbf0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
bc00: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
bc10: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
bc20: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
bc30: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
bc40: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
bc50: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
bc60: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
bc70: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
bc80: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
bc90: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
bca0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
bcb0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
bcc0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
bcd0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
bce0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
bcf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
bd00: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
bd10: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
bd20: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
bd30: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
bd40: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
bd50: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
bd60: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
bd70: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
bd80: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
bd90: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
bda0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
bdb0: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
bdc0: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
bdd0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
bde0: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
bdf0: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
be00: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
be10: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
be20: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
be30: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
be40: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
be50: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
be60: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
be70: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
be80: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
be90: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
bea0: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
beb0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
bec0: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
bed0: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
bee0: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
bef0: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
bf00: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
bf10: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
bf20: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
bf30: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
bf40: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
bf50: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
bf60: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
bf70: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
bf80: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
bf90: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
bfa0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
bfb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bfc0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
bfd0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
bfe0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
bff0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
c000: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
c010: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
c020: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
c030: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
c040: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
c050: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
c060: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
c070: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
c080: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
c090: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
c0a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
c0b0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
c0c0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
c0d0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
c0e0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
c0f0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
c100: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
c110: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
c120: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
c130: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
c140: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
c150: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
c160: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
c170: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
c180: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
c190: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
c1a0: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
c1b0: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
c1c0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
c1d0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
c1e0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
c1f0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
c200: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
c210: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
c220: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c230: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
c240: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
c250: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
c260: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
c270: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
c280: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
c290: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
c2a0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
c2b0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
c2c0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
c2d0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
c2e0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
c2f0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
c300: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
c310: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c320: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
c330: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
c340: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
c350: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
c360: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
c370: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
c380: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
c390: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
c3a0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
c3b0: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
c3c0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
c3d0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
c3e0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
c3f0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
c400: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
c410: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
c420: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
c430: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
c440: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
c450: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
c460: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
c470: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
c480: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
c490: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
c4a0: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
c4b0: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
c4c0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
c4d0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
c4e0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
c4f0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
c500: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
c510: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
c520: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c530: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
c540: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
c550: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
c560: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
c570: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
c580: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
c590: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
c5a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c5b0: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
c5c0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
c5d0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
c5e0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
c5f0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
c600: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
c610: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
c620: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
c630: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
c640: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
c650: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
c660: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
c670: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
c680: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
c690: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c6a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c6b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
c6c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
c6d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c6e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
c6f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
c700: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
c710: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
c720: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
c730: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
c740: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
c750: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
c760: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
c770: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
c780: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
c790: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
c7a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
c7b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
c7c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
c7d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
c7e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c7f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
c800: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
c810: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
c820: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
c830: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
c840: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
c850: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c860: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
c870: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c880: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
c890: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
c8a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
c8b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
c8c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
c8d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
c8f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
c900: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
c910: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
c920: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c930: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
c940: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
c950: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
c960: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
c970: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
c980: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
c990: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
c9a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
c9b0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
c9c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
c9d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
c9e0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
c9f0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
ca00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
ca10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
ca20: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
ca30: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca40: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
ca50: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
ca60: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
ca70: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
ca80: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
ca90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
caa0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
cab0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
cac0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
cad0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
cae0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
caf0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
cb00: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
cb10: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
cb20: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
cb30: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
cb40: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
cb50: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
cb60: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
cb70: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
cb80: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
cb90: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
cba0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
cbb0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
cbc0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
cbd0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
cbe0: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
cbf0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
cc00: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
cc10: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
cc20: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
cc30: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
cc40: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
cc50: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
cc60: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
cc70: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
cc80: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
cc90: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
cca0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
ccb0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
ccc0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ccd0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
cce0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
ccf0: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
cd00: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
cd10: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
cd20: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
cd30: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
cd40: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
cd50: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
cd60: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
cd70: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
cd80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cd90: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
cda0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
cdb0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
cdc0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
cdd0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
cde0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
cdf0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
ce00: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
ce10: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
ce20: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
ce30: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
ce40: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
ce50: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ce60: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
ce70: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
ce80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ce90: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
cea0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
ceb0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cec0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
ced0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
cee0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
cef0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
cf00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
cf10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
cf20: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
cf30: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
cf40: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
cf50: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
cf60: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
cf70: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
cf80: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
cf90: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
cfa0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
cfb0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
cfc0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cfd0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
cfe0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
cff0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
d000: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
d010: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
d020: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
d030: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
d040: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
d050: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
d060: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
d070: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
d080: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
d090: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
d0a0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
d0b0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
d0c0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
d0d0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
d0e0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
d0f0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
d100: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
d110: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d120: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
d130: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d140: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d150: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d160: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
d170: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
d180: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
d190: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
d1a0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
d1b0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
d1c0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
d1d0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
d1e0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
d1f0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
d200: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
d210: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
d220: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
d230: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
d240: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
d250: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
d260: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
d270: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
d280: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
d290: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
d2a0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
d2b0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
d2c0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
d2d0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
d2e0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
d2f0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
d300: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
d310: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
d320: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
d330: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
d340: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
d350: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d360: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
d370: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
d380: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
d390: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d3a0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d3b0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d3c0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d3d0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d3e0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d3f0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d400: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
d410: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
d420: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
d430: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
d440: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
d450: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
d460: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
d470: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
d480: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
d490: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d4a0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d4b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d4c0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
d4d0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
d4e0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
d4f0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
d500: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
d510: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
d520: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
d530: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
d540: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
d550: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
d560: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
d570: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
d580: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d590: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
d5a0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
d5b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d5c0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
d5d0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
d5e0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
d5f0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
d600: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
d610: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
d620: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d630: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d640: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
d650: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d660: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
d670: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d680: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d690: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
d6a0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
d6b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
d6c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
d6d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d6e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
d6f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
d700: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
d710: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
d720: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d730: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
d740: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
d750: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
d760: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
d770: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
d780: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
d790: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d7a0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
d7b0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d7c0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
d7d0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
d7e0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
d7f0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
d800: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
d810: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
d820: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
d830: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
d840: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d850: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
d860: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
d870: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
d880: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
d890: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
d8a0: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
d8b0: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
d8c0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
d8d0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
d8e0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
d8f0: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
d900: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
d910: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
d920: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d930: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
d940: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
d950: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
d960: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
d970: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
d980: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
d990: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
d9a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
d9b0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
d9c0: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
d9d0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
d9e0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
d9f0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
da00: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
da10: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
da20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
da30: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
da40: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
da50: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
da60: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
da70: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
da80: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
da90: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
daa0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
dab0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
dac0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
dad0: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
dae0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
daf0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
db00: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
db10: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
db20: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
db30: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
db40: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
db50: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
db60: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
db70: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
db80: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
db90: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
dba0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
dbb0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
dbc0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
dbd0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
dbe0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
dbf0: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
dc00: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
dc10: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
dc20: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
dc30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
dc40: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
dc50: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
dc60: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
dc70: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
dc80: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
dc90: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
dca0: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
dcb0: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
dcc0: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69  equired due to i
dcd0: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
dce0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
dcf0: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
dd00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
dd10: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
dd20: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
dd30: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
dd40: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
dd50: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
dd60: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
dd70: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70  scratch buffer p
dd80: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
dd90: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
dda0: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
ddb0: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
ddc0: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53   of threads.  ^S
ddd0: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
dde0: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
ddf0: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
de00: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
de10: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
de20: 61 73 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65  ase.** page size
de30: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
de40: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
de50: 6e 61 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  nal scratch memo
de60: 72 79 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68  ry beyond .** wh
de70: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
de80: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
de90: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
dea0: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
deb0: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
dec0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ded0: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
dee0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
def0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
df00: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
df10: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
df20: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
df30: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
df40: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
df50: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
df60: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
df70: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
df80: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
df90: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
dfa0: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
dfb0: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
dfc0: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
dfd0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
dfe0: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
dff0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
e000: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
e010: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
e020: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
e030: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
e040: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e050: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
e060: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
e070: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
e080: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e090: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e0a0: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e0b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e0c0: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e0d0: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
e0e0: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
e0f0: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
e100: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
e110: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
e120: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
e130: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
e140: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
e150: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
e160: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
e170: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
e180: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
e190: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
e1a0: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
e1b0: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
e1c0: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
e1d0: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
e1e0: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
e1f0: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
e200: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
e210: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e220: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e230: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e240: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e250: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
e260: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e270: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
e280: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
e290: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
e2a0: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
e2b0: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
e2c0: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
e2d0: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
e2e0: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
e2f0: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
e300: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
e310: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
e320: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
e330: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
e340: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
e350: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
e360: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
e370: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
e380: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65  e space..** ^The
e390: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e3a0: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72  might use one or
e3b0: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62   more of the N b
e3c0: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a  uffers to hold .
e3d0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  ** memory accoun
e3e0: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ting information
e3f0: 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  . The pointer in
e400: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e410: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
e420: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
e430: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
e440: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
e450: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
e460: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
e470: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
e480: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e490: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
e4a0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
e4b0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
e4c0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
e4d0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
e4e0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
e4f0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
e500: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e510: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
e520: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
e530: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
e540: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
e550: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
e560: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
e570: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
e580: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
e590: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
e5a0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e5b0: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
e5c0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
e5d0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
e5e0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
e5f0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
e600: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
e610: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
e620: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
e630: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
e640: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
e650: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
e660: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
e670: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
e680: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
e690: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
e6a0: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
e6b0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
e6c0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e6d0: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
e6e0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
e6f0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
e700: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
e710: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
e720: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
e730: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
e740: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
e750: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
e760: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
e770: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
e780: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
e790: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
e7a0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e7b0: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
e7c0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
e7d0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
e7e0: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
e7f0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
e800: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e810: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e820: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
e830: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
e840: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e850: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
e860: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
e870: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
e880: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
e890: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
e8a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
e8b0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
e8c0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e8d0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
e8e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
e8f0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
e900: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
e910: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e920: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
e930: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
e940: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e950: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
e960: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
e970: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
e980: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
e990: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
e9a0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
e9b0: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
e9c0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e9d0: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
e9e0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
e9f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ea00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ea10: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ea20: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ea30: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ea40: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
ea50: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
ea60: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
ea70: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
ea80: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
ea90: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
eaa0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
eab0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
eac0: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
ead0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
eae0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
eaf0: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
eb00: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
eb10: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
eb20: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
eb30: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
eb40: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
eb50: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
eb60: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
eb70: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
eb80: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
eb90: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
eba0: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
ebb0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
ebc0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
ebd0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
ebe0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
ebf0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
ec00: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
ec10: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
ec20: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
ec30: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
ec40: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
ec50: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
ec60: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
ec70: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
ec80: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
ec90: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
eca0: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
ecb0: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
ecc0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
ecd0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
ece0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ecf0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ed00: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ed10: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ed20: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
ed30: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
ed40: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
ed50: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
ed60: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
ed70: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ed80: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
ed90: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
eda0: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
edb0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
edc0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
edd0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
ede0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
edf0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
ee00: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
ee10: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
ee20: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
ee30: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
ee40: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
ee50: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
ee60: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
ee70: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ee80: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
ee90: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eea0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
eeb0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
eec0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
eed0: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
eee0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
eef0: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
ef00: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
ef10: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
ef20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ef30: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
ef40: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
ef50: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
ef60: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
ef70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
ef80: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
ef90: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
efa0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
efb0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
efc0: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
efd0: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
efe0: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
eff0: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
f000: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
f010: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f020: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
f030: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
f040: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
f050: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
f060: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
f070: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
f080: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
f090: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
f0a0: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
f0b0: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
f0c0: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
f0d0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f0e0: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
f0f0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
f100: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
f110: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
f120: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
f130: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
f140: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f150: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
f160: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
f170: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f180: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f190: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f1a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f1b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
f1c0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
f1d0: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
f1e0: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
f1f0: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
f200: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f210: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
f220: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
f230: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f240: 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
f250: 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
f260: 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
f270: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
f280: 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
f290: 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
f2a0: 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
f2b0: 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
f2c0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
f2d0: 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
f2e0: 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
f2f0: 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
f300: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
f310: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
f320: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
f330: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
f340: 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
f350: 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
f360: 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
f370: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
f380: 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
f390: 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
f3a0: 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
f3b0: 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
f3c0: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
f3d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
f3e0: 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
f3f0: 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
f400: 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
f410: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
f420: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
f430: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
f440: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
f450: 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
f460: 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
f470: 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
f480: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
f490: 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
f4a0: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
f4b0: 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
f4c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
f4d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
f4e0: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
f4f0: 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
f500: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
f510: 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
f520: 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
f530: 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
f540: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
f550: 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
f560: 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
f570: 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
f580: 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
f590: 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
f5a0: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
f5b0: 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
f5c0: 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
f5d0: 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
f5e0: 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
f5f0: 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
f600: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
f610: 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
f620: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
f630: 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
f640: 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
f650: 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
f660: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
f670: 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
f680: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
f690: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
f6a0: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
f6b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
f6c0: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
f6d0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
f6e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f6f0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
f700: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
f710: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f720: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
f730: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
f740: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f750: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
f760: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
f770: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f790: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
f7a0: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
f7b0: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
f7c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f7d0: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
f7e0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
f7f0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
f800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f810: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
f820: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
f830: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
f840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f850: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
f860: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
f870: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
f880: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
f890: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f8a0: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
f8b0: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
f8c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f8d0: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
f8e0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
f8f0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
f900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f910: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
f920: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
f930: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f940: 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
f950: 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
f960: 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
f970: 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
f980: 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
f990: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f9a0: 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
f9b0: 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
f9c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f9d0: 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
f9e0: 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
f9f0: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
fa00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fa10: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
fa20: 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
fa30: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
fa40: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
fa50: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
fa60: 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
fa70: 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
fa80: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
fa90: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
faa0: 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
fab0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
fac0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
fad0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
fae0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
faf0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fb00: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
fb10: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
fb20: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
fb30: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
fb40: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
fb50: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
fb60: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
fb70: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
fb80: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
fb90: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
fba0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
fbb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fbc0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
fbd0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
fbe0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
fbf0: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
fc00: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
fc10: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fc20: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
fc30: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
fc40: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
fc50: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
fc60: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
fc70: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
fc80: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
fc90: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
fca0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
fcb0: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
fcc0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
fcd0: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
fce0: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
fcf0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
fd00: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
fd10: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
fd20: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
fd30: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
fd40: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
fd50: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
fd60: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
fd70: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
fd80: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
fd90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fda0: 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
fdb0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
fdc0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
fdd0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
fde0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
fdf0: 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
fe00: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
fe10: 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
fe20: 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
fe30: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
fe40: 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
fe50: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
fe60: 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
fe70: 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
fe80: 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
fe90: 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
fea0: 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
feb0: 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
fec0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
fed0: 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
fee0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
fef0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
ff00: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
ff10: 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
ff20: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
ff30: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
ff40: 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
ff50: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
ff60: 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
ff70: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
ff80: 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
ff90: 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
ffa0: 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
ffb0: 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
ffc0: 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
ffd0: 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
ffe0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
fff0: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
10000 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
10010 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10020 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10030 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
10040 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
10050 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
10060 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
10070 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
10080 6d 61 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70  maller.** multip
10090 6c 65 20 6f 66 20 38 2e 20 20 53 65 65 20 61 6c  le of 8.  See al
100a0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  so: [SQLITE_CONF
100b0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64  IG_LOOKASIDE]</d
100c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
100d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
100e0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
100f0 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
10100 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
10110 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
10120 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
10130 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
10140 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
10150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
10160 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
10170 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
10180 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
10190 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
101a0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
101b0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
101c0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
101d0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
101e0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
101f0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
10200 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
10210 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
10220 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
10230 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
10240 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
10250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10260 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
10270 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
10280 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
10290 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
102a0 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
102b0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
102c0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
102d0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
102e0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
102f0 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
10300 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
10310 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
10320 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
10330 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
10340 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
10350 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
10360 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
10370 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
10380 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
10390 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
103a0 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
103b0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
103c0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
103d0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
103e0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
103f0 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
10400 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
10410 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
10420 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10430 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10440 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
10450 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
10460 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10470 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
10480 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10490 74 2e 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  t.  ^If no succe
104a0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
104b0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
104c0 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
104d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
104e0 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
104f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
10500 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
10510 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
10520 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72  ger, then the [r
10530 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
10540 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20  erted.** row is 
10550 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
10560 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
10570 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
10580 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
10590 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
105a0 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
105b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
105c0 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
105d0 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f  ne.** reverts to
105e0 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
105f0 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
10600 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
10610 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  d.)^.**.** ^An [
10620 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
10630 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
10640 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
10650 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
10660 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
10670 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
10680 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
10690 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
106a0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
106b0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
106c0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
106d0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
106e0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
106f0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
10700 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
10710 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
10720 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
10730 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
10740 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
10750 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
10760 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
10770 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
10780 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
10790 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
107a0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
107b0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
107c0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
107d0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
107e0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
107f0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
10800 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
10810 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
10820 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
10830 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
10840 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
10850 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
10860 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
10870 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
10880 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
10890 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
108a0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
108b0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
108c0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
108d0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
108e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
108f0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
10900 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
10910 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
10920 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
10930 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
10940 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
10950 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
10960 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
10970 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
10980 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
10990 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
109a0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
109b0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
109c0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
109d0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
109e0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
109f0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
10a00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
10a10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
10a20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10a30 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
10a40 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
10a50 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
10a60 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
10a70 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
10a80 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
10a90 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
10aa0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10ab0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
10ac0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
10ad0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
10ae0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
10af0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
10b00 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
10b10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
10b20 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
10b30 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
10b40 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
10b50 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
10b60 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
10b70 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
10b80 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
10b90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10ba0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
10bb0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
10bc0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
10bd0 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
10be0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
10bf0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
10c00 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
10c10 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
10c20 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
10c30 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
10c40 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
10c50 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
10c60 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
10c70 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
10c80 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
10c90 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
10ca0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10cb0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
10cc0 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
10cd0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
10ce0 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
10cf0 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
10d00 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
10d10 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
10d20 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
10d30 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
10d40 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
10d50 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
10d60 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
10d70 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
10d80 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
10d90 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
10da0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
10db0 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
10dc0 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
10dd0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
10de0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
10df0 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
10e00 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
10e10 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
10e20 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
10e30 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
10e40 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
10e50 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
10e60 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
10e70 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
10e80 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
10e90 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
10ea0 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
10eb0 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
10ec0 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
10ed0 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
10ee0 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
10ef0 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
10f00 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
10f10 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
10f20 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
10f30 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
10f40 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
10f50 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
10f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
10f70 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
10f80 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
10f90 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
10fa0 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
10fb0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
10fc0 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
10fd0 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
10fe0 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
10ff0 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
11000 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
11010 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
11020 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
11030 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
11040 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
11050 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
11060 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
11070 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
11080 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
11090 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
110a0 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
110b0 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
110c0 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
110d0 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
110e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
110f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
11100 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
11110 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
11120 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
11130 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
11140 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
11150 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
11160 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
11170 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
11180 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
11190 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
111a0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
111b0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
111c0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
111d0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
111e0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
111f0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
11200 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
11210 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
11220 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
11230 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
11240 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
11250 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
11260 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
11270 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
11280 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11290 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
112a0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
112b0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
112c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
112d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
112e0 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
112f0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
11300 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
11310 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
11320 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
11330 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
11340 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
11350 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
11360 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
11370 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
11380 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
11390 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
113a0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
113b0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
113c0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
113d0 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
113e0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
113f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
11400 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
11410 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
11420 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
11430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
11440 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
11450 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
11460 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
11470 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
11480 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
11490 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
114a0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
114b0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
114c0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
114d0 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
114e0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
114f0 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
11500 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11510 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
11520 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
11530 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
11540 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
11550 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
11560 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
11570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11580 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
11590 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
115a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
115b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
115c0 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
115d0 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
115e0 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
115f0 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
11600 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
11610 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
11620 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
11630 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
11640 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
11650 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
11660 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
11670 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
11680 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
11690 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
116a0 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
116b0 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
116c0 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
116d0 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
116e0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
116f0 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
11700 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
11710 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
11720 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
11730 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11740 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
11750 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
11760 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
11770 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
11780 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
11790 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
117a0 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
117b0 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
117c0 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
117d0 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
117e0 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
117f0 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
11800 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
11810 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
11820 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
11830 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
11840 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
11850 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
11860 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
11870 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
11880 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
11890 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
118a0 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
118b0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
118c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
118d0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
118e0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
118f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11900 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
11910 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
11920 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
11930 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
11940 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
11950 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
11960 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11970 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11980 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11990 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
119a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
119b0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
119c0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
119d0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
119e0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
119f0 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
11a00 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
11a10 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
11a20 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
11a30 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
11a40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
11a50 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
11a60 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
11a70 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
11a80 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
11a90 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
11aa0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
11ab0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
11ac0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
11ad0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
11ae0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
11af0 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74  ** ^It is safe t
11b00 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
11b10 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
11b20 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
11b30 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
11b40 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
11b50 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
11b60 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
11b70 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
11b80 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
11b90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
11ba0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
11bb0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
11bc0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
11bd0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
11be0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11bf0 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
11c00 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20  *.** ^If an SQL 
11c10 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
11c20 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
11c30 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
11c40 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
11c50 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
11c60 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
11c70 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
11c80 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
11c90 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
11ca0 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
11cb0 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
11cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20  ..**.** ^An SQL 
11cd0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
11ce0 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
11cf0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
11d00 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
11d10 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75   ^If the interru
11d20 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69  pted SQL operati
11d30 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c  on is an INSERT,
11d40 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11d50 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  TE.** that is in
11d60 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74  side an explicit
11d70 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
11d80 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72  en the entire tr
11d90 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c  ansaction.** wil
11da0 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  l be rolled back
11db0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a   automatically..
11dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11dd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
11de0 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63  call is in effec
11df0 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72  t until all curr
11e00 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a  ently running.**
11e10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
11e20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
11e30 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c  nection] D compl
11e40 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53  ete.  ^Any new S
11e50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
11e60 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
11e70 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
11e80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11e90 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20  call and before 
11ea0 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  the .** running 
11eb0 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68  statements reach
11ec0 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65  es zero are inte
11ed0 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68  rrupted as if th
11ee0 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72  ey had been.** r
11ef0 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20  unning prior to 
11f00 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11f10 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e  rrupt() call.  ^
11f20 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  New SQL statemen
11f30 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
11f40 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
11f50 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
11f60 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73  nt count reaches
11f70 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74   zero are.** not
11f80 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65   effected by the
11f90 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11fa0 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  pt()..** ^A call
11fb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   to sqlite3_inte
11fc0 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63  rrupt(D) that oc
11fd0 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20  curs when there 
11fe0 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a  are no running.*
11ff0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
12000 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20   is a no-op and 
12010 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
12020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
12030 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
12040 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
12050 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12060 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a  ) call returns..
12070 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74  **.** If the dat
12080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12090 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
120a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
120b0 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e  ()].** is runnin
120c0 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67  g then bad thing
120d0 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61  s will likely ha
120e0 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  ppen..*/.void sq
120f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12100 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
12110 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
12120 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
12130 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
12140 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
12150 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
12160 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
12170 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
12180 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
12190 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
121a0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
121b0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
121c0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
121d0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
121e0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
121f0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
12200 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
12210 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
12220 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
12230 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
12240 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
12250 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
12260 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
12270 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
12280 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
12290 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
122a0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
122b0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
122c0 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
122d0 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
122e0 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
122f0 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
12300 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
12310 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
12320 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
12330 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
12340 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
12350 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
12360 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
12370 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
12380 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
12390 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
123a0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
123b0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
123c0 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
123d0 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
123e0 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
123f0 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
12400 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
12410 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
12420 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
12430 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
12440 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
12450 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
12460 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
12470 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
12480 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
12490 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
124a0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
124b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
124c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
124d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
124e0 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
124f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
12500 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
12510 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
12520 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
12530 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
12540 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
12550 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
12560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
12570 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
12580 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
12590 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
125a0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
125b0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
125c0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
125d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
125e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
125f0 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
12600 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
12610 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
12620 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
12630 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
12640 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
12650 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
12660 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
12670 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
12680 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
12690 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
126a0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
126b0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
126c0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
126d0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
126e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
126f0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12700 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12710 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12720 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12730 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
12740 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
12750 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
12760 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
12770 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
12780 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12790 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
127a0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
127b0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
127c0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
127d0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
127e0 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e  Y Errors.**.** ^
127f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
12800 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
12810 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
12820 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
12830 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
12840 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
12850 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
12860 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
12870 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
12880 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
12890 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
128a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
128b0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
128c0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
128d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
128e0 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
128f0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12900 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12910 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20   the lock.  ^If 
12920 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
12930 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
12940 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
12950 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76  ack might be inv
12960 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
12970 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  guments..**.** ^
12980 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12990 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68  nt to the busy h
129a0 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
129b0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
129c0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
129d0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
129e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
129f0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
12a00 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
12a10 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20  ument to.** the 
12a20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c  busy handler cal
12a30 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
12a40 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
12a50 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
12a60 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
12a70 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
12a80 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
12a90 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
12aa0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12ab0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12ac0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12ad0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12ae0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12af0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12b00 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12b10 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12b20 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
12b30 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
12b40 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
12b50 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
12b60 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
12b70 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
12b80 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
12b90 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  ng and the cycle
12ba0 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
12bb0 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
12bc0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
12bd0 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
12be0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
12bf0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
12c00 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
12c10 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
12c20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
12c30 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
12c40 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
12c50 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
12c60 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
12c70 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
12c80 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
12c90 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
12ca0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12cb0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
12cc0 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
12cd0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
12ce0 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
12cf0 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
12d00 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
12d10 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
12d20 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
12d30 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
12d40 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
12d50 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
12d60 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
12d70 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
12d80 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
12d90 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
12da0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
12db0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
12dc0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
12dd0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
12de0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
12df0 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
12e00 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
12e10 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
12e20 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
12e30 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
12e40 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
12e50 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
12e60 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
12e70 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
12e80 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
12e90 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
12ea0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
12eb0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
12ec0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
12ed0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
12ee0 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
12ef0 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
12f00 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
12f10 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
12f20 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
12f30 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
12f40 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
12f50 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
12f60 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
12f70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
12f80 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  L..**.** ^The [S
12f90 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f  QLITE_BUSY] erro
12fa0 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74  r is converted t
12fb0 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  o [SQLITE_IOERR_
12fc0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e  BLOCKED].** when
12fd0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68   SQLite is in th
12fe0 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61  e middle of a la
12ff0 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  rge transaction 
13000 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a  where all the.**
13010 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f   changes will no
13020 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69  t fit into the i
13030 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20  n-memory cache. 
13040 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20   SQLite will.** 
13050 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52  already hold a R
13060 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20  ESERVED lock on 
13070 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
13080 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a  e, but it needs.
13090 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  ** to promote th
130a0 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55  is lock to EXCLU
130b0 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20  SIVE so that it 
130c0 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a  can spill cache.
130d0 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68  ** pages into th
130e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
130f0 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20  without harm to 
13100 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  concurrent.** re
13110 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69  aders.  ^If it i
13120 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d  s unable to prom
13130 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68  ote the lock, th
13140 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  en the in-memory
13150 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62  .** cache will b
13160 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63  e left in an inc
13170 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20  onsistent state 
13180 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72  and so the error
13190 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d  .** code is prom
131a0 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65  oted from the re
131b0 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20  latively benign 
131c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f  [SQLITE_BUSY] to
131d0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76  .** the more sev
131e0 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  ere [SQLITE_IOER
131f0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68  R_BLOCKED].  ^Th
13200 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
13210 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
13220 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
13230 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
13240 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
13250 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
13260 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
13270 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
13280 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
13290 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
132a0 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
132b0 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
132c0 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
132d0 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
132e0 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ortant..**.** ^(
132f0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
13300 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
13310 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
13320 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
13330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13340 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
13350 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
13360 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
13370 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
13380 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
13390 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
133a0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
133b0 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f  ()].** will also
133c0 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68   set or clear th
133d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
133e0 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
133f0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
13400 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
13410 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
13420 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
13430 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
13440 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13450 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20  y handler.  Any 
13460 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
13470 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
13480 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
13490 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
134a0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
134b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
134c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
134d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
134e0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
134f0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
13500 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
13510 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13520 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
13530 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
13540 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
13550 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
13560 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
13570 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
13580 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
13590 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
135a0 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
135b0 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
135c0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
135d0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
135e0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
135f0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
13600 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
13610 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
13620 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
13630 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
13640 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
13650 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
13660 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
13670 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
13680 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
13690 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
136a0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
136b0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
136c0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
136d0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
136e0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
136f0 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
13700 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
13710 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
13720 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
13730 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
13740 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
13750 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
13760 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
13770 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
13780 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13790 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
137a0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
137b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
137c0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
137d0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
137e0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
137f0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
13800 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13810 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
13820 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
13830 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
13840 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
13850 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
13860 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  d.)^.*/.int sqli
13870 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
13880 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
13890 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
138a0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
138b0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
138c0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
138d0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
138e0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
138f0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
13900 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
13910 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
13920 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
13930 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
13940 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
13950 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
13960 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
13970 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
13980 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
13990 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
139a0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
139b0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
139c0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
139d0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
139e0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
139f0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
13a00 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
13a10 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
13a20 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
13a30 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
13a40 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
13a50 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
13a60 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
13a70 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
13a80 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
13a90 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
13aa0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
13ab0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
13ac0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
13ad0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
13ae0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
13af0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
13b00 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
13b10 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
13b20 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
13b30 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
13b40 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
13b50 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
13b60 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
13b70 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
13b80 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
13b90 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
13ba0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
13bb0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
13bc0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
13bd0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
13be0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
13bf0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
13c00 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
13c10 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
13c20 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
13c30 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
13c40 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
13c50 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
13c60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
13c70 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
13c80 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
13c90 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
13ca0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
13cb0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
13cc0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
13cd0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
13ce0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13cf0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
13d00 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70  *.** As an examp
13d10 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
13d20 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
13d30 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
13d40 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
13d50 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
13d60 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13d70 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
13d80 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
13d90 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
13da0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
13db0 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
13dc0 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
13dd0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
13de0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
13df0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
13e00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13e10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
13e20 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
13e30 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
13e40 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
13e50 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
13e60 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
13e70 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
13e80 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13e90 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
13ea0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
13eb0 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
13ec0 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
13ed0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
13ee0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13ef0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
13f00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
13f10 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
13f20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13f30 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
13f40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13f50 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
13f60 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13f70 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
13f80 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
13f90 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
13fa0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
13fb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
13fc0 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
13fd0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13fe0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
13ff0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14000 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
14010 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14020 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  quote>.**.** ^Th
14030 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
14040 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
14050 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
14060 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
14070 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
14080 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
14090 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
140a0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
140b0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
140c0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
140d0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
140e0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
140f0 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
14100 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
14110 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
14120 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
14130 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
14140 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
14150 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14160 29 2c 0a 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20  ),.** it should 
14170 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
14180 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
14190 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
141a0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
141b0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
141c0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
141d0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
141e0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
141f0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
14200 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
14210 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
14220 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
14230 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
14240 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
14250 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
14260 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
14270 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
14280 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14290 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
142a0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
142b0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
142c0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  safely..**.** ^(
142d0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
142e0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
142f0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
14300 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
14310 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
14320 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
14330 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14340 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
14350 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
14360 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
14370 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
14380 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
14390 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
143a0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
143b0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
143c0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
143d0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
143e0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
143f0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
14400 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
14410 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
14420 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
14430 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
14440 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
14450 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
14460 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
14470 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
14480 73 67 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20  sg()].)^.*/.int 
14490 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
144a0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
144b0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
144c0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
144d0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
144e0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
144f0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
14500 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
14510 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
14520 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
14530 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
14540 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
14550 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
14560 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
14570 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
14580 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
14590 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
145a0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
145b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
145c0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
145d0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
145e0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
145f0 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
14600 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
14610 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
14620 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
14630 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
14640 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
14650 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
14660 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
14670 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
14680 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
14690 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
146a0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
146b0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
146c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
146d0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
146e0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
146f0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
14700 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
14710 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
14720 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
14730 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
14740 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
14750 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
14760 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
14770 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
14780 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
14790 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
147a0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
147b0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
147c0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
147d0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
147e0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
147f0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
14800 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
14810 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
14820 20 5e 28 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e   ^(In sqlite3_sn
14830 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
14840 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
14850 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
14860 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
14870 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
14880 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
14890 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
148a0 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
148b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
148c0 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
148d0 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
148e0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
148f0 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
14900 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
14910 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
14920 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
14930 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
14940 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
14950 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
14960 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
14970 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
14980 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
14990 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
149a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
149b0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
149c0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
149d0 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
149e0 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
149f0 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
14a00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
14a10 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
14a20 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
14a30 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
14a40 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
14a50 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
14a60 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
14a70 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
14a80 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
14a90 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
14aa0 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
14ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14ac0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
14ad0 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
14ae0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
14af0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
14b00 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
14b10 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
14b20 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
14b30 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
14b40 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
14b50 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
14b60 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
14b70 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
14b80 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
14b90 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
14ba0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
14bb0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
14bc0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
14bd0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
14be0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
14bf0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
14c00 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
14c10 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
14c20 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
14c30 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
14c40 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
14c50 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
14c60 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
14c70 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
14c80 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
14c90 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
14ca0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
14cb0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
14cc0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
14cd0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
14ce0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
14cf0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
14d00 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
14d10 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
14d20 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
14d30 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
14d40 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
14d50 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
14d60 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
14d70 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
14d80 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
14d90 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
14da0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
14db0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
14dc0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
14dd0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
14de0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
14df0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
14e00 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
14e10 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
14e20 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
14e30 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
14e40 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
14e50 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
14e60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
14e70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
14e80 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
14e90 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
14ea0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
14eb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14ec0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14ed0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
14ee0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
14ef0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
14f00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14f10 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
14f20 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
14f30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
14f40 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
14f50 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
14f60 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
14f70 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
14f80 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
14f90 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
14fa0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
14fb0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
14fc0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
14fd0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
14fe0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
14ff0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15000 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
15010 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
15020 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
15030 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
15040 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
15050 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
15060 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
15070 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
15080 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15090 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
150a0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
150b0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
150c0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
150d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
150e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
150f0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
15100 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
15110 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
15120 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
15130 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
15140 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
15150 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15160 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
15170 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
15180 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
15190 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
151a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
151b0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
151c0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
151d0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
151e0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
151f0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
15200 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
15210 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
15220 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
15230 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
15240 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
15250 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
15260 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
15270 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
15280 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
15290 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
152a0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
152b0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
152c0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
152d0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
152e0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
152f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
15300 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
15310 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
15320 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
15330 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
15340 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
15350 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
15360 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
15370 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
15380 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
15390 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
153a0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
153b0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
153c0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
153d0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
153e0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
153f0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
15400 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
15420 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
15430 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
15440 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
15450 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
15460 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
15470 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
15480 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
15490 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
154a0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
154b0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
154c0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
154d0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
154e0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
154f0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
15500 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
15510 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
15520 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15530 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
15540 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
15550 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
15560 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
15570 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
15580 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
15590 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
155a0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
155b0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
155c0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
155d0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a  t char*, ...);..
155e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
155f0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
15600 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
15610 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
15620 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
15630 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
15640 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
15650 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
15660 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
15670 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
15680 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
15690 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
156a0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
156b0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
156c0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
156d0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
156e0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
156f0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
15700 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
15710 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
15720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
15730 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
15740 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
15750 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
15760 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
15770 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
15780 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
15790 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
157a0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
157b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
157c0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
157d0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
157e0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
157f0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
15800 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
15810 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
15820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15830 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
15840 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
15850 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
15860 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
15870 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
15880 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
15890 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
158a0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
158b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
158c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
158d0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
158e0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
158f0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
15900 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
15910 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
15920 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
15930 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
15940 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
15950 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
15960 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
15970 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
15980 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
15990 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
159a0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
159b0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
159c0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
159d0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
159e0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
159f0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
15a00 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
15a10 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
15a20 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
15a30 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
15a40 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
15a50 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
15a60 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
15a70 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
15a80 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
15a90 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
15aa0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
15ab0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
15ac0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
15ad0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
15ae0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
15af0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
15b00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
15b10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
15b20 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
15b30 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
15b40 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
15b50 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
15b60 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
15b70 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
15b80 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
15b90 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
15ba0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
15bb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
15bc0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
15bd0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15be0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
15bf0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15c00 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15c10 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
15c20 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
15c30 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
15c40 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
15c50 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
15c60 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
15c70 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
15c80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15c90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15ca0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15cb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15cc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
15cd0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
15ce0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
15cf0 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
15d00 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
15d10 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
15d20 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
15d30 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
15d40 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
15d50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
15d60 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
15d70 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
15d80 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
15d90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
15da0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
15db0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
15dc0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
15dd0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
15de0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
15df0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
15e00 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
15e10 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
15e20 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
15e30 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
15e40 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
15e50 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
15e60 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
15e70 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
15e80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15e90 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
15ea0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
15eb0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
15ec0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
15ed0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
15ee0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15ef0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
15f00 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
15f10 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
15f20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
15f30 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
15f40 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
15f50 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
15f60 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
15f70 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a  byte boundary..*
15f80 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
15f90 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
15fa0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
15fb0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
15fc0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
15fd0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
15fe0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
15ff0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
16000 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
16010 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
16020 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
16030 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
16040 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
16050 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
16060 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
16070 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
16080 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
16090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
160a0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
160b0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
160c0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
160d0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
160e0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
160f0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
16100 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
16110 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
16120 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
16130 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
16140 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
16150 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
16160 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
16170 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
16180 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
16190 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
161a0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
161b0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
161c0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
161d0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
161e0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
161f0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
16200 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
16210 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
16220 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
16230 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16240 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
16250 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
16260 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
16270 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
16280 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
16290 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
162a0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
162b0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
162c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
162d0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
162e0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
162f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
16300 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
16310 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
16320 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
16330 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
16340 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
16350 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
16360 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
16370 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
16380 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
16390 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
163a0 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
163b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
163c0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
163d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
163e0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
163f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
16400 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
16410 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
16420 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
16430 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
16440 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
16450 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
16460 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
16470 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
16480 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
16490 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
164a0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
164b0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
164c0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
164d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
164e0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
164f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
16500 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
16510 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
16520 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
16530 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
16540 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
16550 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
16560 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
16570 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
16580 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
16590 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
165a0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
165b0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
165c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
165d0 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
165e0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
165f0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
16600 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
16610 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
16620 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
16630 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
16640 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16650 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
16660 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
16670 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
16680 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
16690 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
166a0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
166b0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
166c0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
166d0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
166e0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
166f0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
16700 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
16710 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
16720 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
16730 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
16740 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
16750 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
16760 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16770 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
16780 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
16790 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
167a0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
167b0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
167c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
167d0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
167e0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
167f0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
16800 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
16810 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
16820 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
16830 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
16840 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
16850 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16860 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16870 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
16880 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
16890 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
168a0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
168b0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
168c0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
168d0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
168e0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
168f0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
16900 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
16910 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
16920 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
16930 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
16940 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
16950 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
16960 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
16970 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
16980 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
16990 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
169a0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
169b0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
169c0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
169d0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
169e0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
169f0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
16a00 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
16a10 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
16a20 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
16a30 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
16a40 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
16a50 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
16a60 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
16a70 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ffer P..**.** ^T
16a80 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
16a90 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
16aa0 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
16ab0 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
16ac0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
16ad0 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
16ae0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
16af0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
16b00 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
16b10 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
16b20 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
16b30 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
16b40 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73  ct..** ^On all s
16b50 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
16b60 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
16b70 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
16b80 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
16b90 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
16ba0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
16bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
16bc0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
16bd0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
16be0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
16bf0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
16c00 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
16c10 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
16c20 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
16c30 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
16c40 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
16c50 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
16c60 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
16c70 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
16c80 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
16c90 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
16ca0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
16cb0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
16cc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16cd0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16ce0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
16cf0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
16d00 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
16d10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
16d20 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
16d30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16d40 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
16d50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
16d60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
16d70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
16d80 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
16d90 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
16da0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
16db0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
16dc0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
16dd0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
16de0 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
16df0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16e00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16e10 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
16e20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
16e30 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
16e40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16e50 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
16e60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
16e70 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
16e80 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
16e90 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
16ea0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
16eb0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
16ec0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
16ed0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
16ee0 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
16ef0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
16f00 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
16f10 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
16f20 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
16f30 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
16f40 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
16f50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16f60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
16f70 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
16f80 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
16f90 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
16fa0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
16fb0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
16fc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16fd0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
16fe0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
16ff0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
17000 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
17010 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
17020 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
17030 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
17040 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17050 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
17060 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
17070 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
17080 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
17090 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
170a0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
170b0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
170c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
170d0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
170e0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
170f0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
17100 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
17110 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
17120 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
17130 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
17140 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
17150 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
17160 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17170 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17180 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
17190 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
171a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
171b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
171c0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
171d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
171e0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
171f0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
17200 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
17210 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
17220 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
17230 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
17240 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
17250 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
17260 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
17270 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
17280 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
17290 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
172a0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
172b0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
172c0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
172d0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
172e0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
172f0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
17300 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
17310 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
17320 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
17330 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
17340 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
17350 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
17360 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
17370 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
17380 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
17390 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
173a0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
173b0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
173c0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
173d0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
173e0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
173f0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
17400 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
17410 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
17420 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
17430 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
17440 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
17450 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
17460 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
17470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
17480 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
17490 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
174a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
174b0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
174c0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
174d0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
174e0 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
174f0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
17500 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
17510 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
17520 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
17530 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
17540 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
17550 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
17560 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
17570 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
17580 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
17590 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
175a0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
175b0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
175c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
175d0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
175e0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
175f0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
17600 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
17610 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
17620 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
17630 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
17640 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
17650 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
17660 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
17670 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
17680 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
17690 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
176a0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
176b0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
176c0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
176d0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
176e0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
176f0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
17700 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
17710 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
17720 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
17730 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
17740 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
17750 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
17760 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
17770 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
17780 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
17790 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
177a0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
177b0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
177c0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
177d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
177e0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
177f0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
17800 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
17810 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
17820 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
17830 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
17840 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
17850 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17860 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
17870 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
17880 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
17890 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
178a0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
178b0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
178c0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
178d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
178e0 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
178f0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
17900 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
17910 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
17920 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
17930 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
17940 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
17950 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
17960 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
17970 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
17980 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
17990 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
179a0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
179b0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
179c0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
179d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
179e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
179f0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
17a00 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
17a10 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
17a20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17a30 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
17a40 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17a50 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
17a60 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
17a70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
17a80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17a90 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
17aa0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
17ab0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
17ac0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
17ad0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
17ae0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
17af0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
17b00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
17b10 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
17b20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
17b30 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
17b40 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
17b50 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
17b60 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
17b70 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
17b80 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
17b90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
17ba0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
17bb0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
17bc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17bd0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
17be0 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
17bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17c00 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
17c10 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
17c20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
17c30 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
17c40 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
17c50 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
17c60 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
17c70 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
17c80 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
17c90 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
17ca0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
17cb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
17cc0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
17cd0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
17ce0 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
17cf0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
17d00 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
17d10 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
17d20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
17d30 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
17d40 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
17d50 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
17d60 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
17d70 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
17d80 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
17d90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17da0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
17db0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17dc0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
17dd0 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
17de0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
17df0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
17e00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
17e10 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17e20 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17e30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17e40 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
17e50 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
17e60 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
17e70 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
17e80 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
17e90 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
17ea0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
17eb0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
17ec0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
17ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
17ee0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17ef0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
17f00 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
17f10 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
17f20 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
17f30 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
17f40 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
17f50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
17f60 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
17f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
17f80 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
17f90 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
17fa0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
17fb0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
17fc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17fd0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
17fe0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
17ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
18000 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
18010 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
18020 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18030 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
18040 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
18050 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
18060 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
18070 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
18080 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
18090 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
180a0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
180b0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
180c0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
180d0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
180e0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
180f0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
18100 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
18110 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18120 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
18130 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
18140 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
18150 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
18160 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
18170 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
18180 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
18190 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
181a0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
181b0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
181c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
181d0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
181e0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
181f0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
18200 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
18210 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
18220 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18230 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
18240 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18250 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
18260 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
18270 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
18280 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
18290 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
182a0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
182b0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
182c0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
182d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
182e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
182f0 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
18300 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
18310 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
18320 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
18330 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
18340 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
18350 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
18360 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
18370 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
18380 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
18390 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
183a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
183b0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
183c0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
183d0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
183e0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
183f0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
18400 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
18410 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18420 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18430 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
18440 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
18450 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18460 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18470 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18480 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
18490 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
184a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
184b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
184c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
184d0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
184e0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
184f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18500 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18520 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
18530 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
18540 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
18550 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18560 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18570 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
18580 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
18590 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
185a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
185b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
185c0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
185d0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
185e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
185f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18610 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
18620 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
18630 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
18640 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18650 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
18660 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
18670 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
18680 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18690 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
186a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
186b0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
186c0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
186d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
186e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
186f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18700 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
18710 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
18720 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18730 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18740 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
18750 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
18760 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18770 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
18780 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18790 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
187a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
187b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
187c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
187d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
187e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
187f0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
18800 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
18810 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18820 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18830 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18840 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
18850 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
18860 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18870 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18880 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
18890 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
188a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
188b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
188c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
188d0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
188e0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
188f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18900 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18920 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
18930 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
18940 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18950 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18970 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
18980 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
18990 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
189a0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
189b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
189c0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
189d0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
189e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
189f0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
18a00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18a10 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
18a20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
18a30 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
18a40 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
18a60 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
18a70 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
18a80 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
18a90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
18ab0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
18ac0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
18ad0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
18ae0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
18af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
18b00 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
18b10 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
18b20 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
18b30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18b40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
18b50 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
18b60 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
18b70 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
18b80 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18b90 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
18ba0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
18bb0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
18bc0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
18bd0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
18bf0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
18c00 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
18c10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18c20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18c30 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
18c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
18c50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18c60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18c70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18c80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
18c90 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
18ca0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18cb0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
18cc0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18cd0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
18ce0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
18cf0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18d00 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
18d10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18d20 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
18d30 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
18d40 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
18d50 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
18d60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18d70 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
18d80 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
18d90 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
18da0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
18db0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18dc0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
18dd0 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
18de0 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
18df0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18e00 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
18e10 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
18e20 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
18e30 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
18e40 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
18e50 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
18e60 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
18e70 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
18e80 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
18e90 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
18ea0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
18eb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18ec0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
18ed0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
18ee0 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
18ef0 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
18f00 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
18f10 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
18f20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
18f30 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
18f40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
18f50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18f60 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
18f70 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
18f80 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18f90 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
18fa0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
18fb0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
18fc0 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
18fd0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
18fe0 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
18ff0 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
19000 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
19010 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
19020 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
19030 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
19040 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
19050 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
19060 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
19070 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
19080 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
19090 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
190a0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
190b0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
190c0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
190d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
190e0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
190f0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
19100 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
19110 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
19120 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
19130 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
19140 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
19150 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
19160 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
19170 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  n..*/.void *sqli
19180 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
19190 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
191a0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
191b0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
191c0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
191d0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
191e0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
191f0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
19200 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
19210 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
19220 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
19230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19240 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
19250 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
19260 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f  ^This routine co
19270 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
19280 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
19290 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
192a0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
192b0 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
192c0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
192d0 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
192e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
192f0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
19300 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
19310 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
19320 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
19330 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
19340 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
19350 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
19360 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
19370 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
19380 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
19390 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
193a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
193b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
193c0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
193d0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
193e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
193f0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
19400 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
19410 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
19420 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
19430 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
19440 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
19450 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
19460 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
19470 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
19480 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
19490 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
194a0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
194b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
194c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
194d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
194e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
194f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19500 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19510 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19520 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19530 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
19540 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
19550 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
19560 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
19570 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
19580 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19590 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
195a0 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
195b0 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
195c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
195d0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
195e0 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
195f0 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
19600 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
19610 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65  e argument. ^The
19620 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19630 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
19640 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
19650 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
19660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
19670 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
19680 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
19690 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
196a0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
196b0 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61  n16(). ^(A [data
196c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
196d0 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
196e0 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
196f0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
19700 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
19710 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
19720 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
19730 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
19740 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
19750 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
19760 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
19770 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
19780 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
19790 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
197a0 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
197b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
197c0 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28  .** object.)^ ^(
197d0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
197e0 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f  is opened (and/o
197f0 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65  r created) succe
19800 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a  ssfully, then.**
19810 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
19820 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
19830 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
19840 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
19850 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c  .)^ ^The.** [sql
19860 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
19870 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
19880 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
19890 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
198a0 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
198b0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
198c0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
198d0 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20  error following 
198e0 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79  a failure of any
198f0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
19900 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e  e3_open() routin
19910 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  es..**.** ^The d
19920 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
19930 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
19940 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69   will be UTF-8 i
19950 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  f.** sqlite3_ope
19960 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
19970 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  pen_v2() is call
19980 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36  ed and.** UTF-16
19990 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
199a0 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c  yte order if sql
199b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73  ite3_open16() is
199c0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   used..**.** Whe
199d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
199e0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
199f0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
19a00 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
19a10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
19a20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19a30 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
19a40 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
19a50 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
19a60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
19a70 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
19a80 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
19a90 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
19aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19ab0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
19ac0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
19ad0 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
19ae0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
19af0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
19b00 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
19b10 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
19b20 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
19b30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19b40 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
19b50 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
19b60 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
19b70 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
19b80 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
19b90 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
19ba0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
19bb0 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
19bc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
19bd0 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
19be0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
19bf0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
19c00 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
19c10 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  * and/or [SQLITE
19c20 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
19c30 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a  HE] flags:)^.**.
19c40 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
19c50 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
19c60 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
19c70 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
19c80 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
19c90 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
19ca0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
19cb0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
19cc0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
19cd0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
19ce0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
19cf0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19d00 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
19d10 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
19d20 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
19d30 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
19d40 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
19d50 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
19d60 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
19d70 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
19d80 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
19d90 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
19da0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
19db0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
19dc0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19dd0 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
19de0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19df0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
19e00 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
19e10 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
19e20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
19e30 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
19e40 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
19e50 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
19e60 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
19e70 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
19e80 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
19e90 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
19ea0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
19eb0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
19ec0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
19ed0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
19ee0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
19ef0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
19f00 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
19f10 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
19f20 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
19f30 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
19f40 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
19f50 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
19f60 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20  above or one of 
19f70 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  the combinations
19f80 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d   shown above com
19f90 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  bined.** with th
19fa0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
19fb0 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
19fc0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19fd0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
19fe0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 61  N_SHAREDCACHE] a
19ff0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1a000 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1a010 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  flags,.** then t
1a020 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
1a030 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
1a040 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
1a050 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1a060 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
1a070 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a080 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
1a090 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
1a0a0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
1a0b0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
1a0c0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
1a0d0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
1a0e0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
1a0f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1a100 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
1a110 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
1a120 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
1a130 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
1a140 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a150 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
1a160 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
1a170 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1a180 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
1a190 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
1a1a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
1a1b0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
1a1c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1a1d0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
1a1e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1a1f0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1a200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a210 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
1a220 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
1a230 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
1a240 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
1a250 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1a260 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
1a270 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
1a280 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
1a290 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1a2a0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
1a2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1a2c0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
1a2d0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1a2e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1a2f0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
1a300 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
1a310 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
1a320 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
1a330 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a340 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65  filename is ":me
1a350 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70  mory:", then a p
1a360 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1a370 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  y in-memory data
1a380 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74  base.** is creat
1a390 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1a3a0 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e  ction.  ^This in
1a3b0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1a3c0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1a3d0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1a3e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1a3f0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1a400 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1a410 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1a420 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1a430 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1a440 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1a450 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1a460 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1a470 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1a480 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1a490 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1a4a0 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1a4b0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1a4c0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1a4d0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1a4e0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1a4f0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1a500 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1a510 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1a520 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1a530 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1a540 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1a550 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1a560 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1a570 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1a580 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61  ed.  ^This priva
1a590 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1a5a0 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1a5b0 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1a5c0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1a5d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a5e0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1a5f0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
1a600 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a610 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1a620 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1a630 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1a640 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1a650 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1a660 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1a670 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1a680 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1a690 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1a6a0 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
1a6b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1a6c0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1a6d0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1a6e0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1a6f0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1a700 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1a710 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1a720 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1a730 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1a740 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1a750 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1a760 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1a780 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1a790 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1a7a0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1a7b0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1a7c0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1a7d0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1a7e0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1a7f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1a800 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1a810 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1a820 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1a830 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1a840 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e  open_v2()..*/.in
1a850 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1a860 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1a870 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a880 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a890 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1a8a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1a8b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a8c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a8d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1a8e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1a8f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1a900 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1a910 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1a920 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a930 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a940 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a950 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a960 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1a970 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1a980 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a990 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a9a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1a9b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1a9c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a9d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a9e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1a9f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1aa00 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1aa10 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1aa20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1aa30 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1aa40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aa50 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1aa60 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
1aa70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1aa80 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1aa90 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1aaa0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1aab0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1aac0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1aad0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1aae0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1aaf0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1ab00 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1ab10 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1ab20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1ab30 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1ab40 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1ab50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1ab60 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1ab70 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1ab80 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1ab90 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1aba0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
1abb0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
1abc0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
1abd0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
1abe0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
1abf0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
1ac00 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
1ac10 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1ac20 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
1ac30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1ac40 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
1ac50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1ac60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1ac70 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1ac80 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1ac90 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1aca0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1acb0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1acc0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1acd0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1ace0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
1acf0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ad00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1ad10 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1ad20 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1ad30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1ad40 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1ad50 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1ad60 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1ad70 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1ad80 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1ad90 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1ada0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1adb0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1adc0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1add0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1ade0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
1adf0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
1ae00 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1ae10 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
1ae20 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
1ae30 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
1ae40 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
1ae50 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
1ae60 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
1ae70 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
1ae80 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
1ae90 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
1aea0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
1aeb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
1aec0 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
1aed0 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
1aee0 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
1aef0 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
1af00 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
1af10 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
1af20 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
1af30 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
1af40 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
1af50 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
1af60 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
1af70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1af80 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
1af90 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1afa0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
1afb0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1afc0 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
1afd0 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
1afe0 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
1aff0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
1b000 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
1b010 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
1b020 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
1b030 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
1b040 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
1b050 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
1b060 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1b070 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1b080 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1b090 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1b0a0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1b0b0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1b0c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1b0d0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1b0e0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1b0f0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1b100 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1b110 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
1b120 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1b130 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
1b140 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1b150 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
1b160 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1b170 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1b180 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1b190 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1b1a0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1b1b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1b1c0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1b1d0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
1b1e0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1b1f0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1b200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1b210 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1b220 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1b230 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1b240 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1b250 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1b260 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1b270 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1b280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b290 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1b2a0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1b2b0 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1b2c0 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1b2d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1b2e0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1b2f0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1b300 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1b310 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1b320 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1b330 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1b340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b350 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1b360 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1b370 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1b380 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1b390 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1b3a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1b3b0 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1b3c0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1b3d0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1b3e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1b3f0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1b400 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1b410 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1b420 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1b430 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1b440 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1b450 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1b460 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1b470 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1b480 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1b490 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1b4a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1b4b0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1b4c0 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1b4d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1b4e0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1b4f0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1b500 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1b510 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1b520 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1b530 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1b540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b550 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1b560 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
1b570 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1b580 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1b590 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1b5a0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1b5b0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1b5c0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1b5d0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1b5e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1b5f0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1b600 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1b610 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1b620 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1b630 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1b640 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1b650 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1b660 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1b670 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1b680 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1b690 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1b6a0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1b6b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1b6c0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1b6d0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1b6e0 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1b6f0 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1b700 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  mit.)^.**.** ^If
1b710 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1b720 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1b730 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1b740 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1b750 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  ^(For the limit 
1b760 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1b770 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1b780 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
1b790 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
1b7a0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62   bound].** set b
1b7b0 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1b7c0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1b7d0 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20  macro named .** 
1b7e0 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
1b7f0 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54  _MAX_XYZ]..** (T
1b800 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1b810 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1b820 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1b830 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1b840 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1b850 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1b860 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1b870 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1b880 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1b890 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1b8a0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
1b8b0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1b8c0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1b8d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1b8e0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1b8f0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1b900 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1b910 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1b920 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1b930 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1b940 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1b950 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1b960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1b970 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
1b980 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
1b990 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
1b9a0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
1b9b0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
1b9c0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
1b9d0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
1b9e0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
1b9f0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
1ba00 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
1ba10 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
1ba20 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
1ba30 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
1ba40 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
1ba50 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
1ba60 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
1ba70 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1ba80 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
1ba90 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
1baa0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
1bab0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
1bac0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
1bad0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
1bae0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
1baf0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
1bb00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1bb10 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
1bb20 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
1bb30 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
1bb40 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
1bb50 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
1bb60 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
1bb70 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
1bb80 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
1bb90 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
1bba0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
1bbb0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
1bbc0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
1bbd0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
1bbe0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
1bbf0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
1bc00 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
1bc10 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
1bc20 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
1bc30 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
1bc40 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1bc50 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
1bc60 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1bc70 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1bc80 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
1bc90 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
1bca0 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
1bcb0 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
1bcc0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
1bcd0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
1bce0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
1bcf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
1bd00 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
1bd10 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
1bd20 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1bd30 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
1bd40 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
1bd50 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
1bd60 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
1bd70 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
1bd80 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
1bd90 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
1bda0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1bdb0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
1bdc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bdd0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
1bde0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
1bdf0 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
1be00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1be10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1be20 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1be30 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1be40 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
1be50 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
1be60 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
1be70 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1be80 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
1be90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bea0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1beb0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
1bec0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
1bed0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
1bee0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
1bef0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
1bf00 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1bf10 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
1bf20 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
1bf30 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
1bf40 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
1bf50 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1bf60 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1bf70 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1bf80 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1bf90 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1bfa0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1bfb0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
1bfc0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1bfd0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
1bfe0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
1bff0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c000 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
1c010 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
1c020 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
1c030 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c040 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1c050 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
1c060 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c070 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
1c080 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
1c090 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
1c0a0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
1c0b0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
1c0c0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1c0d0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c0e0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1c0f0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
1c100 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c110 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
1c120 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
1c130 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c140 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c150 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1c160 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c170 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
1c180 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
1c190 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
1c1a0 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  d>.**.** ^(<dt>S
1c1b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1c1c0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1c1d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c1e0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c1f0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1c200 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
1c210 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
1c220 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
1c230 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c240 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1c250 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1c260 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c270 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1c280 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1c290 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1c2a0 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1c2b0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
1c2c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c2d0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1c2e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c2f0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1c300 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
1c310 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
1c320 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1c330 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c340 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1c350 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1c360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c370 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1c380 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1c390 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c3a0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1c3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1c3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c3d0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1c3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1c3f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c400 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1c410 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1c420 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1c430 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1c440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c450 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1c460 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1c470 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1c480 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1c490 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1c4a0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1c4b0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1c4c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1c4d0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1c4e0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1c4f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1c500 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1c510 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
1c520 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1c530 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
1c540 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
1c550 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
1c560 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
1c570 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
1c580 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
1c590 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
1c5a0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
1c5b0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
1c5c0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
1c5d0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
1c5e0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
1c5f0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
1c600 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
1c610 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1c620 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
1c630 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c640 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
1c650 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
1c660 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1c670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1c680 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1c690 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
1c6a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1c6b0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
1c6c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
1c6d0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
1c6e0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1c6f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c700 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
1c710 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1c720 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
1c730 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
1c740 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
1c750 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
1c760 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
1c770 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1c780 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
1c790 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
1c7a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1c7b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1c7c0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
1c7d0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
1c7e0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
1c7f0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
1c800 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
1c810 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
1c820 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
1c830 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1c840 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
1c850 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1c860 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1c870 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1c880 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1c890 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
1c8a0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1c8b0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
1c8c0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
1c8d0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
1c8e0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
1c8f0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
1c900 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
1c910 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
1c920 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
1c930 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
1c940 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
1c950 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
1c960 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
1c970 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
1c980 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
1c990 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
1c9a0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
1c9b0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
1c9c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
1c9d0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
1c9e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1c9f0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
1ca00 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
1ca10 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
1ca20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
1ca30 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ytes..**.** ^If 
1ca40 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55  pzTail is not NU
1ca50 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20  LL then *pzTail 
1ca60 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1ca70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1ca80 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65  te.** past the e
1ca90 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
1caa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1cab0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1cac0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63  utines only.** c
1cad0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1cae0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1caf0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1cb00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1cb10 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69  to.** what remai
1cb20 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ns uncompiled..*
1cb30 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73  *.** ^*ppStmt is
1cb40 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1cb50 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72  o a compiled [pr
1cb60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cb70 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a  ] that can be.**
1cb80 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20   executed using 
1cb90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cba0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  .  ^If there is 
1cbb0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d  an error, *ppStm
1cbc0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e  t is set.** to N
1cbd0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e  ULL.  ^If the in
1cbe0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1cbf0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1cc00 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1cc10 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1cc20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1cc30 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1cc40 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63  o NULL..** The c
1cc50 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
1cc60 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1cc70 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
1cc80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
1cc90 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1cca0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1ccb0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
1ccc0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1ccd0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d   it..** ppStmt m
1cce0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a  ay not be NULL..
1ccf0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73  **.** ^On succes
1cd00 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70  s, the sqlite3_p
1cd10 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20  repare() family 
1cd20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  of routines retu
1cd30 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a  rn [SQLITE_OK];.
1cd40 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  ** otherwise an 
1cd50 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1cd60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1cd70 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1cd80 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1cd90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1cda0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1cdb0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1cdc0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1cdd0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1cde0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1cdf0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1ce00 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1ce10 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1ce20 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1ce30 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e  iscouraged..** ^
1ce40 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
1ce50 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70  rfaces, the prep
1ce60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
1ce70 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e  * that is return
1ce80 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
1ce90 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63  _stmt] object) c
1cea0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f  ontains a copy o
1ceb0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61  f the.** origina
1cec0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73  l SQL text. This
1ced0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c   causes the [sql
1cee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74  ite3_step()] int
1cef0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68  erface to.** beh
1cf00 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20  ave differently 
1cf10 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a  in three ways:.*
1cf20 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
1cf30 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74  >.** ^If the dat
1cf40 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
1cf50 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66  nges, instead of
1cf60 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
1cf70 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74  TE_SCHEMA] as it
1cf80 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20  .** always used 
1cf90 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f  to do, [sqlite3_
1cfa0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74  step()] will aut
1cfb0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1cfc0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20  pile the SQL.** 
1cfd0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72  statement and tr
1cfe0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69  y to run it agai
1cff0 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63 68 65  n.  ^If the sche
1d000 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1d010 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1d020 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1d030 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1d040 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1d050 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1d060 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1d070 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1d080 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1d090 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1d0a0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1d0b0 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1d0c0 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1d0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d0e0 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1d0f0 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1d100 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1d110 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1d120 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1d130 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1d140 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1d150 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1d160 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1d170 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1d180 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1d190 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1d1a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1d1b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d1c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1d1d0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1d1e0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1d1f0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1d200 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1d210 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1d220 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1d230 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d240 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1d250 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1d260 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1d270 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1d280 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1d290 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1d2a0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1d2b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1d2c0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1d2d0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1d2e0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1d2f0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1d300 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1d310 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1d320 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1d330 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1d340 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d350 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1d360 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1d370 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  i>.** ^If the va
1d380 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65  lue of a [parame
1d390 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
1d3a0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45  eter] in the WHE
1d3b0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a  RE clause might.
1d3c0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 71 75  ** change the qu
1d3d0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
1d3e0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74  tatement, then t
1d3f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79  he statement may
1d400 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1d410 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20  ally recompiled 
1d420 28 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64  (as if there had
1d430 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63   been a schema c
1d440 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69  hange) on the fi
1d450 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rst .** [sqlite3
1d460 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
1d470 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
1d480 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73  ge to the .** [s
1d490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1d4a0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
1d4b0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  the [parameter].
1d4c0 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f   .** </li>.** </
1d4d0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
1d4e0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1d4f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d500 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1d510 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1d520 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1d530 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1d540 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1d550 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1d560 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1d570 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1d580 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1d590 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1d5a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1d5b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1d5c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1d5d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1d5e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1d5f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1d600 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1d610 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1d620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d630 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d640 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d650 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d660 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1d670 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d680 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d690 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1d6a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1d6b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1d6c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1d6d0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1d6e0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1d6f0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1d700 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1d710 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1d720 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1d730 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1d740 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1d750 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1d760 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d770 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1d780 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1d790 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1d7a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1d7b0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1d7c0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1d7d0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1d7e0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1d7f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1d800 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1d810 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1d820 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1d830 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1d840 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1d850 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1d860 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1d870 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1d880 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1d890 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1d8a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1d8b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1d8c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d8d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1d8e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1d8f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1d900 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1d910 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1d920 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1d930 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1d940 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1d950 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1d960 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1d970 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1d980 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1d990 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1d9a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d9b0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1d9c0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1d9d0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1d9e0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1d9f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da00 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1da10 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1da20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1da30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
1da40 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
1da50 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
1da60 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
1da70 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
1da80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1da90 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
1daa0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
1dab0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
1dac0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
1dad0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1dae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1daf0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
1db00 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1db10 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
1db20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
1db30 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
1db40 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
1db50 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
1db60 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
1db70 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1db80 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
1db90 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
1dba0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
1dbb0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1dbc0 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
1dbd0 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
1dbe0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
1dbf0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
1dc00 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
1dc10 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
1dc20 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
1dc30 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
1dc40 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
1dc50 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
1dc60 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
1dc70 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
1dc80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
1dc90 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
1dca0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
1dcb0 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
1dcc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
1dcd0 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
1dce0 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
1dcf0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
1dd00 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
1dd10 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
1dd20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
1dd30 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
1dd40 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
1dd50 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
1dd60 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
1dd70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1dd80 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
1dd90 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
1dda0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
1ddb0 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
1ddc0 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
1ddd0 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
1dde0 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
1ddf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1de00 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
1de10 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
1de20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
1de30 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
1de40 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
1de50 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74   is held.  A int
1de60 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
1de70 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
1de80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1de90 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
1dea0 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
1deb0 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
1dec0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1ded0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
1dee0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
1def0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
1df00 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
1df10 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
1df20 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
1df30 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
1df40 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
1df50 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
1df60 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
1df70 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
1df80 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
1df90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
1dfa0 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
1dfb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1dfc0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
1dfd0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
1dfe0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
1dff0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1e000 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1e010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e020 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
1e030 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
1e040 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
1e050 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
1e060 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
1e070 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
1e080 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
1e090 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
1e0a0 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
1e0b0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1e0c0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
1e0d0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
1e0e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1e0f0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
1e100 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
1e110 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
1e120 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1e130 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1e140 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1e150 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1e160 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1e170 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1e180 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1e190 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1e1a0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
1e1b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
1e1c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
1e1d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
1e1e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
1e1f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
1e200 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
1e210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e220 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
1e230 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
1e240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
1e250 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
1e260 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
1e270 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
1e280 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
1e290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
1e2a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
1e2b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
1e2c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
1e2d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e2e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
1e2f0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
1e300 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
1e310 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1e320 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
1e330 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
1e340 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1e350 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1e360 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1e370 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1e380 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1e390 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1e3a0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1e3b0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1e3c0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1e3d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1e3e0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1e3f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1e400 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1e410 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1e420 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1e430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1e440 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1e450 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1e460 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1e470 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1e480 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1e490 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1e4a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1e4b0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1e4c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1e4d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1e4e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1e4f0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1e500 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1e510 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1e520 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1e530 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1e540 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1e550 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1e560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e570 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1e580 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1e590 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
1e5a0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
1e5b0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
1e5c0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
1e5d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
1e5e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1e5f0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
1e600 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
1e610 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
1e620 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
1e630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1e640 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
1e650 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e660 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
1e670 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
1e680 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
1e690 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
1e6a0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
1e6b0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
1e6c0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
1e6d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
1e6e0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
1e6f0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
1e700 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
1e710 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
1e720 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
1e730 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
1e740 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
1e750 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
1e760 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
1e770 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
1e780 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
1e790 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  ifer.)^  ^The va
1e7a0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1e7b0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1e7c0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1e7d0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1e7e0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1e7f0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1e800 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1e810 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1e820 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1e830 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
1e840 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1e850 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
1e860 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e870 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
1e880 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1e890 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1e8a0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
1e8b0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
1e8c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
1e8d0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
1e8e0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
1e8f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
1e900 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
1e910 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
1e920 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
1e930 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
1e940 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
1e950 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
1e960 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
1e970 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
1e980 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
1e990 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
1e9a0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
1e9b0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
1e9c0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
1e9d0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
1e9e0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
1e9f0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
1ea00 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
1ea10 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
1ea20 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
1ea30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ea40 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
1ea50 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
1ea60 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1ea70 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1ea80 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1ea90 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
1eaa0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
1eab0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
1eac0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1ead0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
1eae0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1eaf0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
1eb00 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
1eb10 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
1eb20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1eb30 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
1eb40 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
1eb50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
1eb60 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
1eb70 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
1eb80 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
1eb90 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1eba0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1ebb0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
1ebc0 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
1ebd0 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
1ebe0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
1ebf0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
1ec00 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
1ec10 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1ec20 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
1ec30 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1ec40 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
1ec50 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
1ec60 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
1ec70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1ec80 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
1ec90 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1eca0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
1ecb0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1ecc0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
1ecd0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
1ece0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
1ecf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
1ed00 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
1ed10 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
1ed20 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
1ed30 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
1ed40 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
1ed50 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
1ed60 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69  h it. ^If the fi
1ed70 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1ed80 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1ed90 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1eda0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1edb0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1edc0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1edd0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1ede0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1edf0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1ee00 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1ee10 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
1ee20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1ee30 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1ee40 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1ee50 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1ee60 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1ee70 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1ee80 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1ee90 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1eea0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1eeb0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1eec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1eed0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
1eee0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
1eef0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
1ef00 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
1ef10 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
1ef20 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
1ef30 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
1ef40 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
1ef50 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
1ef60 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
1ef70 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
1ef80 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
1ef90 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
1efa0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
1efb0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
1efc0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
1efd0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
1efe0 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
1eff0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1f000 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
1f010 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
1f020 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
1f030 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
1f040 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
1f050 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
1f060 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
1f070 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
1f080 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
1f090 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1f0a0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
1f0b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1f0c0 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
1f0d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1f0e0 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
1f0f0 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
1f100 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
1f110 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
1f120 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
1f130 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
1f140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
1f150 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
1f160 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1f170 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
1f180 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
1f190 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
1f1a0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
1f1b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f1c0 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
1f1d0 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
1f1e0 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
1f1f0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
1f200 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1f210 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
1f220 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
1f230 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
1f240 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
1f250 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
1f260 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
1f270 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
1f280 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f290 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
1f2a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1f2b0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1f2c0 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
1f2d0 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
1f2e0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
1f2f0 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20  ^[SQLITE_RANGE] 
1f300 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
1f310 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1f320 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
1f330 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45  range.  ^[SQLITE
1f340 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72  _NOMEM] is retur
1f350 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20  ned if malloc() 
1f360 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  fails..**.** See
1f370 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1f380 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1f390 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
1f3a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f3b0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1f3c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f3d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f3e0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1f3f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
1f400 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f410 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1f420 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1f430 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1f440 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
1f450 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f460 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
1f470 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
1f480 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f490 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
1f4a0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
1f4b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f4c0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
1f4d0 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
1f4e0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
1f4f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
1f500 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f510 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
1f520 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
1f530 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
1f540 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1f550 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
1f560 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
1f570 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1f580 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
1f590 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1f5a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
1f5b0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
1f5c0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
1f5d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
1f5e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f5f0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
1f600 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1f610 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
1f620 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1f630 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
1f640 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1f650 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
1f660 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1f670 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
1f680 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
1f690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f6a0 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
1f6b0 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
1f6c0 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
1f6d0 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
1f6e0 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
1f6f0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
1f700 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
1f710 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
1f720 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
1f730 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
1f740 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
1f750 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
1f760 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
1f770 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
1f780 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
1f790 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1f7a0 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
1f7b0 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
1f7c0 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
1f7d0 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
1f7e0 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
1f7f0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
1f800 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
1f810 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
1f820 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
1f830 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
1f840 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
1f850 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
1f860 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
1f870 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1f880 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1f890 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1f8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f8b0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1f8c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1f8d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1f8e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1f8f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f900 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
1f910 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
1f920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
1f930 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
1f940 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  meter.**.** ^The
1f950 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1f960 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
1f970 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f980 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
1f990 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
1f9a0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1f9b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1f9c0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
1f9d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
1f9e0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
1f9f0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1fa00 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1fa10 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
1fa20 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
1fa30 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
1fa40 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1fa50 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
1fa60 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
1fa70 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
1fa80 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
1fa90 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
1faa0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
1fab0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
1fac0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
1fad0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1fae0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1faf0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1fb00 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1fb10 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
1fb20 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
1fb30 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
1fb40 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
1fb50 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1fb60 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
1fb70 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1fb80 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
1fb90 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
1fba0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
1fbb0 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
1fbc0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
1fbd0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
1fbe0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
1fbf0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
1fc00 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
1fc10 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
1fc20 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
1fc30 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
1fc40 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
1fc50 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
1fc60 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
1fc70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
1fc80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1fc90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1fca0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1fcb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1fcc0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1fcd0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1fce0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1fcf0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
1fd00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fd10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1fd20 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1fd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fd40 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
1fd50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1fd60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fd70 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
1fd80 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
1fd90 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
1fda0 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
1fdb0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
1fdc0 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
1fdd0 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
1fde0 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
1fdf0 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
1fe00 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
1fe10 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
1fe20 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
1fe30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1fe40 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
1fe50 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
1fe60 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
1fe70 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
1fe80 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
1fe90 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
1fea0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
1feb0 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
1fec0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1fed0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
1fee0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
1fef0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
1ff00 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ff10 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1ff20 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1ff30 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1ff40 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1ff50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1ff60 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1ff70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ff80 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ff90 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1ffa0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1ffb0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
1ffc0 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
1ffd0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
1ffe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
1fff0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
20000 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
20010 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
20020 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
20030 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
20040 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
20050 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
20060 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
20070 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
20080 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
20090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
200a0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
200b0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
200c0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
200d0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
200e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
200f0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
20100 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
20110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
20120 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
20130 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
20140 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
20150 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
20160 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
20170 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
20180 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
20190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
201a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
201b0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
201c0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
201d0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
201e0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
201f0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
20200 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f 0a 69   [UPDATE])..*/.i
20210 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
20220 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
20230 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
20240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
20250 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
20260 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
20270 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
20280 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
20290 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
202a0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
202b0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
202c0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
202d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
202e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
202f0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
20300 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
20310 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
20320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20330 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
20340 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
20350 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
20360 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
20370 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
20380 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
20390 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
203a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
203b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
203c0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
203d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
203e0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
203f0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
20400 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
20410 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
20420 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
20430 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
20440 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
20450 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
20460 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
20470 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
20480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20490 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
204a0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
204b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
204c0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
204d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
204e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
204f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
20500 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
20510 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
20520 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
20530 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
20540 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
20550 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
20560 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
20570 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
20580 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
20590 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
205a0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
205b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
205c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
205d0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
205e0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
205f0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
20600 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
20610 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
20620 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
20630 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
20640 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
20650 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
20660 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
20670 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
20680 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
20690 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
206a0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
206b0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e  the next..*/.con
206c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
206d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
206e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
206f0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
20700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20710 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20720 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
20730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
20740 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
20750 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
20760 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
20770 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
20780 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
20790 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
207a0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
207b0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
207c0 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
207d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
207e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
207f0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
20800 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
20810 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
20820 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
20830 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
20840 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
20850 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
20860 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
20870 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
20880 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
20890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
208a0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
208b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
208c0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
208d0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
208e0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
208f0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
20900 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
20910 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
20920 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
20930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20940 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
20950 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
20960 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
20970 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
20980 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
20990 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
209a0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
209b0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
209c0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
209d0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
209e0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
209f0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
20a00 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
20a10 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
20a20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
20a30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
20a40 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
20a50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
20a60 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
20a70 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
20a80 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
20a90 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
20aa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
20ab0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
20ac0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
20ad0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
20ae0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
20af0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
20b00 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
20b10 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
20b20 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
20b30 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
20b40 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
20b50 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
20b60 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
20b70 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
20b80 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
20b90 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
20ba0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
20bb0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
20bc0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
20bd0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
20be0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
20bf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20c00 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
20c10 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
20c20 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
20c30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
20c40 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
20c50 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
20c60 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
20c70 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
20c80 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
20c90 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
20ca0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
20cb0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
20cc0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
20cd0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
20ce0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
20cf0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
20d00 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
20d10 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
20d20 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
20d30 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
20d40 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
20d50 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
20d60 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
20d70 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
20d80 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
20d90 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
20da0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
20db0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
20dc0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
20dd0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20de0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
20df0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
20e00 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
20e10 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
20e20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
20e30 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
20e40 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
20e50 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
20e60 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
20e70 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
20e80 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20e90 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
20ea0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
20eb0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
20ec0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
20ed0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
20ee0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
20ef0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
20f00 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20f10 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20f20 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20f30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20f40 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
20f50 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20f60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20f70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20f80 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
20f90 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20fa0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20fb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20fc0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20fd0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
20fe0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20ff0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
21000 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21010 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
21020 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21030 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
21040 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21050 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
21060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
21070 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
21080 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
21090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
210a0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
210b0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
210c0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
210d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
210e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
210f0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
21100 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
21110 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
21120 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
21130 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
21140 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
21150 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
21160 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
21170 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
21180 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
21190 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
211a0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
211b0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
211c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
211d0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
211e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
211f0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
21200 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
21210 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
21220 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
21230 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
21240 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
21250 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
21260 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
21270 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
21280 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
21290 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
212a0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
212b0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
212c0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
212d0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
212e0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
212f0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
21300 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
21310 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
21320 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
21330 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
21340 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
21350 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
21360 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
21370 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
21380 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
21390 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
213a0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
213b0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
213c0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
213d0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
213e0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
213f0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
21400 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
21410 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
21420 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
21430 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
21440 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
21450 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
21460 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
21470 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
21480 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
21490 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
214a0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
214b0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
214c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
214d0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
214e0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
214f0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
21500 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
21510 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
21520 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21530 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
21540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21550 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
21560 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21570 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
21580 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
21590 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
215a0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
215b0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
215c0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
215d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
215e0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
215f0 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
21600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21610 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
21620 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21630 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
21640 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
21650 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
21660 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
21670 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21680 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
21690 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
216a0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
216b0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
216c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
216d0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
216e0 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
216f0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
21700 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
21710 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
21720 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
21730 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
21740 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
21750 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
21760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
21770 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21790 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
217a0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
217b0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
217c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
217d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
217e0 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
217f0 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
21800 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
21810 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
21820 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
21830 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
21840 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
21850 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
21860 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
21870 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
21880 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
21890 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
218a0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
218b0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
218c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
218d0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
218e0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
218f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
21900 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
21910 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
21920 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
21930 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
21940 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
21950 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
21960 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
21970 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
21980 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
21990 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
219a0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
219b0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
219c0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
219d0 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
219e0 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
219f0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
21a00 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
21a10 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
21a20 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
21a30 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
21a40 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
21a50 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
21a60 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
21a70 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
21a80 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
21a90 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
21aa0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
21ab0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
21ac0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
21ad0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
21ae0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
21af0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
21b00 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
21b10 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
21b20 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
21b30 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
21b40 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
21b50 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
21b60 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
21b70 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
21b80 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21b90 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
21ba0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
21bb0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
21bc0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
21bd0 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
21be0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
21bf0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
21c00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
21c10 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
21c20 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
21c30 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
21c40 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
21c50 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
21c60 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
21c70 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
21c80 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
21c90 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
21ca0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
21cb0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
21cc0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
21cd0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
21ce0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
21cf0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
21d00 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
21d10 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
21d20 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
21d30 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
21d40 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
21d50 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
21d60 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
21d70 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
21d80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
21d90 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
21da0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
21db0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
21dc0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
21dd0 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
21de0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21df0 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
21e00 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
21e10 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
21e20 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
21e30 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
21e40 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
21e50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
21e60 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
21e70 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
21e80 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
21e90 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
21ea0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
21eb0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
21ec0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21ed0 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
21ee0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
21ef0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
21f00 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
21f10 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21f20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
21f30 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
21f40 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
21f50 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
21f60 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
21f70 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
21f80 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
21f90 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
21fa0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21fb0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
21fc0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
21fd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21fe0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
21ff0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
22000 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
22010 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
22020 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
22030 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
22040 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
22050 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
22060 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
22070 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
22080 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
22090 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
220a0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
220b0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
220c0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
220d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
220e0 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
220f0 20 33 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77 61   3.6.23.1, it wa
22100 73 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 61 66  s required.** af
22110 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
22120 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
22130 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
22140 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61  [SQLITE_ROW] tha
22150 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  t.** [sqlite3_re
22160 73 65 74 28 29 5d 20 62 65 20 63 61 6c 6c 65 64  set()] be called
22170 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
22180 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
22190 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
221a0 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
221b0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
221c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
221d0 74 68 69 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a  this way would.*
221e0 2a 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  * result in an [
221f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
22200 65 74 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74  eturn from sqlit
22210 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
22220 61 66 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e  after.** version
22230 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
22240 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 20  e3_step() began 
22250 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
22260 5f 72 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75  _reset()] .** au
22270 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
22280 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
22290 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74   rather than ret
222a0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
222b0 49 53 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  ISUSE].  .**.** 
222c0 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
222d0 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
222e0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
222f0 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
22300 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
22310 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
22320 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
22330 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
22340 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
22350 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
22360 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22370 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
22380 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
22390 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
223a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
223b0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
223c0 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
223d0 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
223e0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
223f0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
22400 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
22410 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
22420 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
22430 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
22440 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
22450 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
22460 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
22470 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
22480 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
22490 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
224a0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
224b0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
224c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
224d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
224e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
224f0 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
22500 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
22510 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
22520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22530 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
22540 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
22550 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
22560 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
22570 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
22580 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
22590 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
225a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
225b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
225c0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
225d0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
225e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
225f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
22600 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
22610 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
22620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
22630 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 20 6e  a_count(P) the n
22640 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22650 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74 68   in the.** of th
22660 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
22670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22680 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] P..*/.int s
22690 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
226a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
226b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
226c0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
226d0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
226e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
226f0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
22700 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
22710 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
22720 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
22730 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
22740 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
22750 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
22760 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
22770 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
22780 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
22790 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
227a0 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
227b0 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
227c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
227d0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
227e0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
227f0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
22800 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
22810 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
22820 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
22830 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
22840 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
22850 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
22860 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
22870 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
22880 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
22890 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
228a0 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
228b0 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
228c0 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
228d0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
228e0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
228f0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
22900 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
22910 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
22920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
22930 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
22940 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
22950 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
22960 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
22970 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
22980 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
22990 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
229a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
229b0 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
229c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
229d0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
229e0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
229f0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
22a00 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
22a10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
22a20 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
22a30 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
22a40 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
22a50 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
22a60 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
22a70 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
22a80 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
22a90 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
22aa0 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
22ab0 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
22ac0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
22ad0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
22ae0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
22af0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
22b00 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
22b10 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
22b20 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
22b30 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
22b40 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
22b50 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
22b60 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
22b70 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
22b80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
22b90 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
22ba0 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
22bb0 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
22bc0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
22bd0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
22be0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
22bf0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
22c00 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
22c10 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
22c20 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
22c30 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
22c40 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
22c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22c60 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
22c70 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
22c80 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
22c90 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
22ca0 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
22cb0 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
22cc0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
22cd0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
22ce0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
22cf0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
22d00 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
22d10 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
22d20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
22d30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
22d40 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
22d50 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
22d60 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
22d70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22d80 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
22d90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
22da0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
22db0 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
22dc0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22dd0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
22de0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
22df0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
22e00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22e10 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
22e20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
22e30 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
22e40 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
22e50 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
22e60 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
22e70 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
22e80 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
22e90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22ea0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
22eb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22ec0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
22ed0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
22ee0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
22ef0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22f00 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
22f10 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
22f20 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
22f30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
22f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
22f50 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
22f60 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
22f70 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
22f80 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
22f90 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
22fa0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
22fb0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
22fc0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
22fd0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
22fe0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
22ff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
23000 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
23010 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
23020 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
23030 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
23040 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
23050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23060 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
23070 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
23080 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
23090 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
230a0 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
230b0 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
230c0 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
230d0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
230e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
230f0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
23100 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
23110 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
23120 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
23130 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
23140 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
23150 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
23160 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
23170 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
23180 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
23190 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
231a0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
231b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
231c0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
231d0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
231e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
231f0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
23200 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
23210 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
23220 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
23230 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23240 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
23250 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
23260 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
23270 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
23280 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
23290 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
232a0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
232b0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
232c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
232d0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
232e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
232f0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
23300 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
23310 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
23320 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
23330 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
23340 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20 76  tring..** ^The v
23350 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
23360 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
23370 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
23380 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
23390 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
233a0 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
233b0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
233c0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
233d0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
233e0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
233f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
23400 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
23410 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
23420 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
23430 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
23440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23450 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
23460 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
23470 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
23480 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
23490 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
234a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
234b0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
234c0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
234d0 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  B is an arbitrar
234e0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
234f0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
23500 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
23510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
23520 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
23530 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
23540 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ar to sqlite3_co
23550 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
23560 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72  but leaves the r
23570 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20  esult in UTF-16 
23580 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
23590 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
235a0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a  UTF-8..** ^The z
235b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
235c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
235d0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
235e0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
235f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
23600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23610 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
23620 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23630 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
23640 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
23650 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
23660 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
23670 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
23680 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
23690 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
236a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
236b0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
236c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
236d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
236e0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
236f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23700 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
23710 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
23720 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
23730 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
23740 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
23750 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
23760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
23770 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
23780 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
23790 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
237a0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
237b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
237c0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
237d0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
237e0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
237f0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
23800 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
23810 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
23820 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
23830 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
23840 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
23850 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
23860 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
23870 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
23880 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
23890 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
238a0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
238b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
238c0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
238d0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
238e0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
238f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
23900 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
23910 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
23920 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
23930 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
23940 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
23950 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
23960 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23970 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
23980 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
23990 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
239a0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
239b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
239c0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
239d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
239e0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
239f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
23a00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
23a10 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
23a20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
23a30 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
23a40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
23a50 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
23a60 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
23a70 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
23a80 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
23a90 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
23aa0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
23ab0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
23ac0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
23ad0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
23ae0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
23af0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
23b00 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
23b10 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
23b20 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
23b30 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23b40 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
23b50 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
23b60 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
23b70 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
23b80 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
23b90 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
23ba0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
23bb0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
23bc0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23bd0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
23be0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
23bf0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
23c00 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
23c10 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
23c20 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
23c30 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
23c40 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
23c50 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23c60 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
23c70 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
23c80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
23c90 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
23ca0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
23cb0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
23cc0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
23cd0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
23ce0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
23cf0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
23d00 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
23d10 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
23d20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
23d30 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
23d40 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23d50 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
23d60 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
23d70 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
23d80 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
23d90 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
23da0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
23db0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
23dc0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
23dd0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
23de0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
23df0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
23e00 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
23e10 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
23e20 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
23e30 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
23e40 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
23e50 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
23e60 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
23e70 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
23e80 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
23e90 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
23ea0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
23eb0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 77  .** ^Note that w
23ec0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
23ed0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
23ee0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
23ef0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
23f00 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
23f10 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
23f20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
23f30 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
23f40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23f50 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
23f60 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70 65  dated..** ^(Type
23f70 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
23f80 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
23f90 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
23fa0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
23fb0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
23fc0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
23fd0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
23fe0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
23ff0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24000 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
24010 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
24020 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
24030 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
24040 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
24050 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
24060 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
24070 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
24080 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
24090 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
240a0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
240b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
240c0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
240d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
240e0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
240f0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
24100 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
24110 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
24120 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
24130 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
24140 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
24150 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
24160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
24170 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
24180 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24190 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
241a0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
241b0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
241c0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
241d0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
241e0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
241f0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
24200 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
24210 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
24220 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
24230 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
24240 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
24250 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
24260 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
24270 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
24280 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
24290 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
242a0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
242b0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
242c0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
242d0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
242e0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
242f0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
24300 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
24310 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
24320 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
24330 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
24340 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
24350 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dated..**.** ^(T
24360 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
24370 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
24380 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
24390 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
243a0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
243b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
243c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
243d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
243e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
243f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
24400 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24410 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
24420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24430 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
24440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24450 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
24460 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
24470 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
24480 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
24490 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
244a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29  )</li>.** </ul>)
244b0 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ^.**.** In other
244c0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
244d0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
244e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
244f0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
24500 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
24510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24520 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
24530 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
24540 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
24550 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
24560 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
24570 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
24580 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
24590 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
245a0 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
245b0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
245c0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
245d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
245e0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
245f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24600 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
24610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
24620 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
24630 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
24640 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
24650 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
24660 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
24670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24680 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
24690 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
246a0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
246b0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
246c0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
246d0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
246e0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
246f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
24700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24710 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
24720 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
24730 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
24740 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
24750 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
24760 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
24770 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
24780 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
24790 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
247a0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
247b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
247c0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
247d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
247e0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
247f0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
24800 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
24810 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
24820 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
24830 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
24840 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
24850 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24860 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
24870 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
24880 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
24890 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
248a0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
248b0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
248c0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
248d0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
248e0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
248f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
24900 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
24910 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
24920 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
24930 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
24940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24950 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24960 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24970 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24980 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
24990 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
249a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
249b0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
249c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
249d0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
249e0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
249f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24a00 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
24a10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
24a20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24a30 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
24a40 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
24a50 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
24a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24a70 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
24a80 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
24a90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24aa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24ab0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
24ac0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
24ad0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
24ae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24af0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24b00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
24b10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24b20 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
24b30 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
24b40 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
24b50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24b60 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
24b70 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
24b80 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24b90 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
24ba0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
24bb0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
24bc0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
24bd0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
24be0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
24bf0 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d  * ^If the statem
24c00 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64  ent was executed
24c10 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72   successfully or
24c20 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74   not executed at
24c30 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51   all, then.** SQ
24c40 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
24c50 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 74 69  ned. ^If executi
24c60 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
24c70 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
24c80 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
24c90 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
24ca0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
24cb0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
24cc0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
24cd0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
24ce0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
24cf0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
24d00 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
24d10 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
24d20 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
24d30 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a  chine has not.**
24d40 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
24d50 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
24d60 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
24d70 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
24d80 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
24d90 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73  n error or an [s
24da0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
24db0 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a   | interrupt]..*
24dc0 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  * ^Incomplete up
24dd0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
24de0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
24df0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
24e00 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
24e10 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
24e20 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
24e30 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
24e40 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
24e50 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
24e60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
24e70 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
24e80 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
24e90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24ea0 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
24eb0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
24ec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24ed0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
24ee0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
24ef0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
24f00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
24f10 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
24f20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
24f30 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
24f40 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
24f50 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
24f60 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
24f70 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
24f80 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
24f90 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
24fa0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
24fb0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
24fc0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
24fd0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
24fe0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
24ff0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
25000 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
25010 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
25020 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
25030 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
25040 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25050 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
25060 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
25070 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
25080 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
25090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
250a0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
250b0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
250c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
250d0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
250e0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
250f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
25100 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
25110 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
25120 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
25130 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
25140 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
25150 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
25160 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
25170 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
25180 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
25190 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
251a0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
251b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
251c0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
251d0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
251e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
251f0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
25200 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
25210 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
25220 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
25230 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
25240 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
25250 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
25260 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
25270 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
25280 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
25290 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
252a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
252b0 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
252c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
252d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
252e0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
252f0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
25300 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
25310 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
25320 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
25330 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
25340 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25350 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
25360 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
25370 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25380 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
25390 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74  ^These two funct
253a0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
253b0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
253c0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
253d0 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
253e0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
253f0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
25400 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
25410 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
25420 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
25430 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
25440 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
25450 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
25460 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
25470 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
25480 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
25490 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
254a0 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
254b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
254c0 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
254d0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
254e0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
254f0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
25500 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
25510 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25520 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
25530 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
25540 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
25550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25560 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
25570 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
25580 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
25590 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
255a0 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
255b0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
255c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
255d0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
255e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
255f0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
25600 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
25610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25620 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
25630 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
25640 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
25650 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
25660 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
25670 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
25680 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
25690 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
256a0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
256b0 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
256c0 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
256d0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
256e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
256f0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
25700 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
25710 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
25720 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
25730 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
25740 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
25750 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
25760 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
25770 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74  ERROR] being ret
25780 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
25790 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
257a0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
257b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
257c0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
257d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
257e0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
257f0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
25800 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
25810 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
25820 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
25830 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
25840 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
25850 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
25860 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
25870 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
25880 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
25890 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
258a0 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
258b0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
258c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
258d0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
258e0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
258f0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
25900 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
25910 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25920 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
25930 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
25940 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
25950 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
25960 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
25970 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
25980 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41  s parameters.  A
25990 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
259a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
259b0 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f  hould be able to
259c0 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69   work.** work wi
259d0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
259e0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
259f0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
25a00 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
25a10 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
25a20 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
25a30 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
25a40 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
25a50 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
25a60 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
25a70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
25a80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
25a90 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
25aa0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
25ab0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
25ac0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
25ad0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
25ae0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
25af0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
25b00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
25b10 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
25b20 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
25b30 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
25b40 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
25b50 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
25b60 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
25b70 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
25b80 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
25b90 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
25ba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
25bb0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
25bc0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
25bd0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
25be0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
25bf0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
25c00 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
25c10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
25c20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
25c30 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
25c40 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
25c50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
25c60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
25c70 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
25c80 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
25c90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
25ca0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
25cb0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
25cc0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
25cd0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
25ce0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
25cf0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
25d00 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
25d10 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
25d20 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
25d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
25d40 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
25d50 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
25d60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
25d70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25d80 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
25d90 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
25da0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
25db0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
25dc0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
25dd0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
25de0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
25df0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
25e00 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
25e10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
25e20 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
25e30 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c  l and NULL shoul
25e40 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  d be passed for 
25e50 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
25e60 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
25e70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
25e80 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
25e90 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68   NULL for all th
25ea0 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ree function cal
25eb0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  lbacks..**.** ^I
25ec0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
25ed0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
25ee0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
25ef0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
25f00 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
25f10 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
25f20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
25f30 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
25f40 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
25f50 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
25f60 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
25f70 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
25f80 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
25f90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25fa0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
25fb0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
25fc0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
25fd0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
25fe0 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
25ff0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26000 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
26010 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
26020 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
26030 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
26040 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
26050 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
26060 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
26070 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
26080 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
26090 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
260a0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
260b0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
260c0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
260d0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
260e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
260f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
26100 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
26110 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
26120 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
26130 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
26140 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
26150 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
26160 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
26170 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
26180 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
26190 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
261a0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
261b0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
261c0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
261d0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
261e0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
261f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26200 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e   functions..** ^
26210 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63  The first applic
26220 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26230 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69  nction with a gi
26240 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64  ven name overrid
26250 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d  es all.** built-
26260 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  in functions in 
26270 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
26280 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
26290 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
262a0 65 2e 0a 2a 2a 20 5e 53 75 62 73 65 71 75 65 6e  e..** ^Subsequen
262b0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
262c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
262d0 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  of the same name
262e0 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a   only override .
262f0 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61  ** prior applica
26300 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26310 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ctions that are 
26320 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66  an exact match f
26330 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  or the.** number
26340 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61   of parameters a
26350 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63  nd preferred enc
26360 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  oding..**.** ^An
26370 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
26390 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
263a0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
263b0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
263c0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
263d0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
263e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
263f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
26400 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
26410 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
26420 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
26430 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
26440 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
26450 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
26460 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
26470 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
26480 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
26490 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
264a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
264b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
264c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
264d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
264e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
264f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
26500 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
26510 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
26520 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
26530 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
26540 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
26550 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
26560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26570 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
26580 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
26590 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
265a0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
265b0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
265c0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
265d0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
265e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
265f0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
26600 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
26610 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
26620 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
26630 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
26640 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
26650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
26660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26670 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
26680 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
26690 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
266a0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
266b0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
266c0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
266d0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
266e0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
266f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26700 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
26710 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
26720 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
26730 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
26740 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
26750 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
26760 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
26770 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
26780 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
26790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
267a0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
267b0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
267c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
267d0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
267e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
267f0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
26800 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
26810 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
26820 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
26830 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
26840 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
26850 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
26860 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
26870 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
26880 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
26890 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
268a0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
268b0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
268c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
268d0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
268e0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
268f0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
26900 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
26910 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
26920 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
26930 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
26940 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
26950 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
26960 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
26970 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
26980 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
26990 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
269a0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
269b0 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
269c0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
269d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
269e0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
269f0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
26a00 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
26a10 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
26a20 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
26a30 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
26a40 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26a50 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
26a60 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
26a70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
26a80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
26a90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
26aa0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
26ab0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
26ac0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
26ad0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
26ae0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
26af0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26b00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
26b10 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
26b20 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
26b30 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
26b40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
26b50 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
26b60 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
26b70 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
26b80 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a  eter Values.**.*
26b90 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
26ba0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26bb0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
26bc0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
26bd0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
26be0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
26bf0 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
26c00 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
26c10 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
26c20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
26c30 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egate..**.** The
26c40 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c   xFunc (for scal
26c50 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72  ar functions) or
26c60 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72   xStep (for aggr
26c70 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65  egates) paramete
26c80 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  rs.** to [sqlite
26c90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26ca0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
26cb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26cc0 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65  n16()].** define
26cd0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20   callbacks that 
26ce0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
26cf0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
26d00 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54  aggregates..** T
26d10 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
26d20 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61   to these callba
26d30 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20  cks is an array 
26d40 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a  of pointers to.*
26d50 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  * [protected sql
26d60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26d70 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f  cts.  There is o
26d80 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ne [sqlite3_valu
26d90 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a  e] object for.**
26da0 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20   each parameter 
26db0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
26dc0 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ion.  These rout
26dd0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
26de0 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75  .** extract valu
26df0 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  es from the [sql
26e00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26e10 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  cts..**.** These
26e20 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f   routines work o
26e30 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63  nly with [protec
26e40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26e50 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41  e] objects..** A
26e60 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ny attempt to us
26e70 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
26e80 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   on an [unprotec
26e90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26ea0 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73  e].** object res
26eb0 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
26ec0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  d behavior..**.*
26ed0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
26ee0 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65  s work just like
26ef0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
26f00 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  ng [column acces
26f10 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20  s functions].** 
26f20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65  except that  the
26f30 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65  se routines take
26f40 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65   a single [prote
26f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26f60 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f  ue] object.** po
26f70 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
26f80 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74   a [sqlite3_stmt
26f90 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61  *] pointer and a
26fa0 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e  n integer column
26fb0 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
26fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
26fd0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
26fe0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
26ff0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
27000 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
27010 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
27020 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
27030 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
27040 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
27050 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
27060 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
27070 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
27080 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
27090 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
270a0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
270b0 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
270c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
270d0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
270e0 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
270f0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
27100 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
27110 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
27120 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
27130 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
27140 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
27150 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
27160 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
27170 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
27180 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
27190 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
271a0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
271b0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
271c0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
271d0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
271e0 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
271f0 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
27200 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
27210 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
27220 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
27230 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
27240 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
27250 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
27260 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
27270 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
27280 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
27290 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  ed.)^.**.** Plea
272a0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
272b0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
272c0 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
272d0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
272e0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
272f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
27300 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
27310 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
27320 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27330 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
27340 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
27350 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
27360 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
27370 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
27380 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27390 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
273a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
273b0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
273c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
273d0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
273e0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
273f0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27400 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
27410 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
27420 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
27430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
27440 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
27450 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
27460 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
27470 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
27480 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
27490 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
274a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
274b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
274c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
274d0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
274e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
274f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
27500 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
27510 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
27520 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
27530 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
27540 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
27550 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27560 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
27570 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
27580 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
27590 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
275a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
275b0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
275c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
275d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
275e0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
275f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
27600 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27610 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
27620 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27630 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27640 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
27650 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
27670 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
27680 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
27690 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
276a0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
276b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
276c0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 69 6f 6e  .** Implemention
276d0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
276e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
276f0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
27700 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
27710 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
27720 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
27730 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
27740 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
27750 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27760 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
27770 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
27780 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
27790 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
277a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
277b0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
277c0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
277d0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
277e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
277f0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
27800 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
27810 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
27820 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
27830 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27840 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
27850 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
27860 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
27870 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
27880 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
27890 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
278a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
278b0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
278c0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
278d0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
278e0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
278f0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
27900 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
27910 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
27920 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
27930 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
27940 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
27950 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
27960 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
27970 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
27980 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
27990 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
279a0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
279b0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
279c0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
279d0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
279e0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
279f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27a00 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
27a10 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
27a20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
27a30 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
27a40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
27a50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27a60 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
27a70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
27a80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
27a90 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
27aa0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
27ab0 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
27ac0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
27ad0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
27ae0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
27af0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
27b00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27b10 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
27b20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
27b30 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
27b40 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
27b50 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
27b60 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
27b70 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
27b80 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
27b90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27ba0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
27bb0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
27bc0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
27bd0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
27be0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
27bf0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
27c00 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
27c10 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
27c20 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
27c30 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
27c40 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
27c50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
27c60 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
27c70 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
27c80 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
27c90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
27ca0 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
27cb0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
27cc0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
27cd0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
27ce0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
27cf0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
27d00 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
27d10 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
27d20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
27d30 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
27d40 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
27d50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
27d60 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
27d70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
27d80 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
27d90 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
27da0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
27db0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
27dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
27dd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27de0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27df0 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
27e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27e10 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
27e20 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
27e30 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
27e40 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
27e50 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
27e60 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
27e70 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
27e80 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
27e90 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
27ea0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
27eb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27ec0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
27ed0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
27ee0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
27ef0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
27f00 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
27f10 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
27f20 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
27f30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27f40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
27f50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27f60 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27f70 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
27f80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27f90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
27fa0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
27fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
27fc0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
27fd0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
27fe0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
27ff0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
28000 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
28010 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
28020 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
28030 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
28040 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
28050 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
28060 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
28070 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
28080 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
28090 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
280a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
280b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
280c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
280d0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
280e0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
280f0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
28100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28110 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
28120 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  n..*/.sqlite3 *s
28130 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
28140 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
28150 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
28160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
28170 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
28180 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
28190 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
281a0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
281b0 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
281c0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
281d0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
281e0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
281f0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
28200 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
28210 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
28220 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
28230 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
28240 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
28250 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
28260 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
28270 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
28280 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
28290 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
282a0 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
282b0 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
282c0 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
282d0 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
282e0 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
282f0 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
28300 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
28310 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
28320 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
28330 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
28340 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
28350 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
28360 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
28370 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
28380 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
28390 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
283a0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
283b0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
283c0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
283d0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
283e0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
283f0 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
28400 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
28410 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
28420 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
28430 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
28440 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
28450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28460 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
28470 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28480 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
28490 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
284a0 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
284b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
284c0 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
284d0 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
284e0 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
284f0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
28500 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28510 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
28520 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
28530 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
28540 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
28550 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
28560 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
28570 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
28580 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
28590 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
285a0 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
285b0 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
285c0 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
285d0 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
285e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
285f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28600 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
28610 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
28620 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
28630 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
28640 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
28650 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
28660 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
28670 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
28680 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
28690 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
286a0 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
286b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
286c0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
286d0 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
286e0 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
286f0 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
28700 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
28710 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
28720 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
28730 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
28740 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
28750 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
28760 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
28770 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
28780 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
28790 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
287a0 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
287b0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
287c0 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
287d0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
287e0 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
287f0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
28800 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
28810 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
28820 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
28830 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
28840 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
28850 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
28860 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
28870 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
28880 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
28890 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
288a0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
288b0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
288c0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
288d0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
288e0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
288f0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
28900 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
28910 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
28920 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
28930 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
28940 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
28950 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
28960 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
28970 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
28980 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28990 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
289a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
289b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
289c0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
289d0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
289e0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
289f0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
28a00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
28a10 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
28a20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
28a30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28a40 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
28a50 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
28a60 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
28a70 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
28a80 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
28a90 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
28aa0 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  r.**.** These ar
28ab0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
28ac0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
28ad0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
28ae0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
28af0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
28b00 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
28b10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28b20 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68  blob()].  ^If th
28b30 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
28b40 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49  argument is SQLI
28b50 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65  TE_STATIC, it me
28b60 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
28b70 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20  tent pointer is 
28b80 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20  constant.** and 
28b90 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67  will never chang
28ba0 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20  e.  It does not 
28bb0 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72  need to be destr
28bc0 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53  oyed.  ^The.** S
28bd0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
28be0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
28bf0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
28c00 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
28c10 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
28c20 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
28c30 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
28c40 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
28c50 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
28c60 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
28c70 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
28c80 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
28c90 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
28ca0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
28cb0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
28cc0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
28cd0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
28ce0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
28cf0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
28d00 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
28d10 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
28d20 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
28d30 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
28d40 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
28d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
28d60 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
28d70 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28d80 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
28d90 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
28da0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
28db0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a  SQL Function.**.
28dc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28dd0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
28de0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
28df0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
28e00 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
28e10 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
28e20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
28e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
28e40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
28e50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
28e60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
28e70 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
28e80 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
28e90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
28ea0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
28eb0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
28ec0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
28ed0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
28ee0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
28ef0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
28f00 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
28f10 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
28f20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
28f30 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
28f40 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
28f50 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
28f60 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
28f70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
28f80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
28f90 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
28fa0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
28fb0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
28fc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28fd0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
28fe0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
28ff0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
29000 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
29010 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
29020 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
29030 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
29040 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
29050 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
29060 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29070 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
29080 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
29090 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
290a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
290b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
290c0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
290d0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
290e0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
290f0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
29100 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
29110 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
29120 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
29130 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29140 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
29150 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29160 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
29170 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29180 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29190 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
291a0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
291b0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
291c0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
291d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
291e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
291f0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
29200 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
29210 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
29220 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
29230 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
29240 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
29250 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
29260 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
29270 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
29280 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
29290 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
292a0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
292b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
292c0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
292d0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
292e0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
292f0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
29300 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
29310 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
29320 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29330 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
29340 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
29350 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
29360 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
29370 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
29380 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
29390 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
293a0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
293b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
293c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
293d0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
293e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
293f0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
29400 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
29410 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
29420 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
29430 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
29440 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
29450 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
29460 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29470 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
29480 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
29490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
294a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
294b0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
294c0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
294d0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
294e0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
294f0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
29500 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
29510 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
29520 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29530 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
29540 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
29550 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
29560 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
29570 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
29580 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
29590 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
295a0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
295b0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
295c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
295d0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
295e0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
295f0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
29600 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
29610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
29620 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
29630 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
29640 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
29650 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
29660 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
29670 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
29680 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
29690 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
296a0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
296b0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
296c0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
296d0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
296e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
296f0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
29700 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
29710 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
29720 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
29730 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
29740 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29750 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63  oobig() interfac
29760 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
29770 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
29780 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
29790 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72  that a string or
297a0 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e   BLOB is too lon
297b0 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a  g to represent..
297c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
297d0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
297e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
297f0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
29800 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
29810 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
29820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
29830 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
29840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29850 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
29860 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29870 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29880 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29890 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
298a0 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
298b0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
298c0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
298d0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
298e0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
298f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29900 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
29910 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
29920 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
29930 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29940 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29950 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
29960 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
29970 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
29980 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
29990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
299a0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
299b0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
299c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
299d0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
299e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
299f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
29a00 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
29a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29a20 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
29a30 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
29a40 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
29a50 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
29a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29a70 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
29a80 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
29a90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
29aa0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29ab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29ac0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
29ad0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
29ae0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
29af0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
29b00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
29b10 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
29b20 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
29b30 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
29b40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
29b50 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
29b60 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
29b70 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
29b80 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
29b90 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
29ba0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
29bb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
29bc0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
29bd0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
29be0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29bf0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29c00 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
29c10 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
29c20 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
29c30 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
29c40 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
29c50 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
29c60 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
29c70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
29c80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29ca0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29cb0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
29cc0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
29cd0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
29ce0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
29cf0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
29d00 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
29d10 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
29d20 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
29d30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
29d40 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
29d50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
29d60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29d70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29d80 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29d90 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
29da0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
29db0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
29dc0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
29dd0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
29de0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
29df0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
29e00 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
29e10 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
29e20 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
29e30 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
29e40 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
29e50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
29e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29e70 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
29e80 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
29e90 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
29ea0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
29eb0 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
29ec0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
29ed0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
29ee0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
29ef0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
29f00 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
29f10 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
29f20 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
29f30 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
29f40 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
29f50 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
29f60 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
29f70 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
29f80 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
29f90 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
29fa0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
29fb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29fc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
29fd0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29fe0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
29ff0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
2a000 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
2a010 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
2a020 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2a030 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
2a040 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
2a050 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
2a060 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
2a070 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
2a080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a090 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a0a0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2a0b0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2a0c0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2a0d0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a0e0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
2a0f0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
2a100 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a110 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
2a120 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
2a130 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
2a140 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2a150 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2a160 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
2a170 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2a180 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
2a190 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
2a1a0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
2a1b0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
2a1c0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
2a1d0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
2a1e0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2a1f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
2a200 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
2a210 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
2a220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
2a240 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
2a250 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
2a260 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a270 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
2a280 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
2a290 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
2a2a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a2b0 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
2a2c0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
2a2d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
2a2e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2a2f0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2a300 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
2a310 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
2a320 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
2a330 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
2a340 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2a350 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
2a360 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
2a370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
2a380 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
2a390 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a3a0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
2a3b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73  e3_result_blob(s
2a3c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a3d0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a3e0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2a3f0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a400 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73  _result_double(s
2a410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a420 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73   double);.void s
2a430 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a440 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
2a450 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2a460 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
2a470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a480 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
2a490 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2a4a0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
2a4b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a4c0 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74  ror_toobig(sqlit
2a4d0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2a4e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a4f0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
2a500 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2a510 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a520 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2a530 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a540 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2a550 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2a560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a570 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2a580 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
2a590 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
2a5a0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
2a5b0 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  4);.void sqlite3
2a5c0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
2a5d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2a5e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a5f0 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ult_text(sqlite3
2a600 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a610 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69   char*, int, voi
2a620 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2a630 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a640 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  t_text16(sqlite3
2a650 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a660 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2a670 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2a680 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a690 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
2a6a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2a6b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
2a6c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2a6d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a6e0 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  lt_text16be(sqli
2a6f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a700 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
2a710 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2a720 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a730 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ult_value(sqlite
2a740 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2a750 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
2a760 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a770 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2a780 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2a790 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2a7a0 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
2a7b0 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
2a7c0 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ces.**.** These 
2a7d0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
2a7e0 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
2a7f0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2a800 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
2a810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a820 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
2a830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2a840 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
2a850 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
2a860 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2a870 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
2a880 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
2a890 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2a8a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2a8b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
2a8c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2a8d0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
2a8e0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
2a8f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a900 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e  llation16(). ^In
2a910 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68   all cases.** th
2a920 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64  e name is passed
2a930 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   as the second f
2a940 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2a950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2a960 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
2a970 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
2a980 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
2a990 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
2a9a0 45 5f 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b  E_UTF16LE], or [
2a9b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2a9c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2a9d0 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
2a9e0 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
2a9f0 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
2aa00 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
2aa10 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
2aa20 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
2aa30 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
2aa40 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
2aa50 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig-endian, respe
2aa60 63 74 69 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a  ctively. ^The.**
2aa70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2aa80 6d 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53  might also be [S
2aa90 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 74 6f 20  QLITE_UTF16] to 
2aaa0 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 74 68  indicate that th
2aab0 65 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70  e routine.** exp
2aac0 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
2aad0 20 62 65 20 55 54 46 2d 31 36 20 73 74 72 69 6e   be UTF-16 strin
2aae0 67 73 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  gs in the native
2aaf0 20 62 79 74 65 20 6f 72 64 65 72 2c 20 6f 72 20   byte order, or 
2ab00 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
2ab10 63 61 6e 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  can be [SQLITE_U
2ab20 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66  TF16_ALIGNED] if
2ab30 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74   the.** the rout
2ab40 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
2ab50 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
2ab60 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
2ab70 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36  ngs.** of UTF-16
2ab80 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
2ab90 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
2aba0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
2abb0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
2abc0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2abd0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
2abe0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
2abf0 20 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c    ^If it is NULL
2ac00 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
2ac10 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
2ac20 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2ac30 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
2ac40 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
2ac50 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
2ac60 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 69 6d 65 20  ..** ^Each time 
2ac70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2ac80 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
2ac90 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
2aca0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73   is passed.** as
2acb0 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
2acc0 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74  eter a copy of t
2acd0 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
2ace0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
2acf0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2ad00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ad10 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ation() or sqlit
2ad20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ad30 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ion16()..**.** ^
2ad40 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72  The remaining ar
2ad50 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61  guments to the a
2ad60 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
2ad70 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20  ied routine are 
2ad80 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20  two strings,.** 
2ad90 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64  each represented
2ada0 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64   by a (length, d
2adb0 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e  ata) pair and en
2adc0 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63  coded in the enc
2add0 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61  oding.** that wa
2ade0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2adf0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77  third argument w
2ae00 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
2ae10 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a  n sequence was.*
2ae20 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 20 54  * registered.  T
2ae30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ae40 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2ae50 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
2ae60 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
2ae70 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
2ae80 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
2ae90 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
2aea0 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
2aeb0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
2aec0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
2aed0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
2aee0 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
2aef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2af00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2af10 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
2af20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
2af30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
2af40 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
2af50 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61  t takes an extra
2af60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
2af70 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2af80 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  for.** the colla
2af90 74 69 6f 6e 2e 20 20 5e 54 68 65 20 64 65 73 74  tion.  ^The dest
2afa0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2afb0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
2afc0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
2afd0 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
2afe0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
2aff0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2b000 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
2b010 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
2b020 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b030 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  n_v2()..** ^Coll
2b040 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
2b050 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
2b060 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
2b070 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
2b080 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
2b090 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
2b0a0 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
2b0b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b0c0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
2b0d0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2b0e0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
2b0f0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
2b100 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b110 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
2b120 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2b130 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
2b140 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2b150 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
2b160 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2b170 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2b180 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2b190 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2b1a0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2b1b0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b1c0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b1d0 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
2b1e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b1f0 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
2b200 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2b210 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2b220 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2b230 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
2b240 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2b250 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2b260 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
2b270 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2b280 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
2b290 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b2a0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
2b2b0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
2b2c0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
2b2d0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2b2e0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2b2f0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2b300 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2b310 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2b320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b330 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
2b340 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
2b350 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
2b360 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
2b370 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
2b380 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
2b390 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
2b3a0 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
2b3b0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
2b3c0 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
2b3d0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
2b3e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2b3f0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69  nection] to be i
2b400 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2b410 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  an undefined col
2b420 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2b430 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ce is required..
2b440 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75  **.** ^If the fu
2b450 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74  nction is regist
2b460 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
2b470 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2b480 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a  _needed() API,.*
2b490 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73  * then it is pas
2b4a0 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  sed the names of
2b4b0 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2b4c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61  tion sequences a
2b4d0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63  s strings.** enc
2b4e0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e  oded in UTF-8. ^
2b4f0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
2b500 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
2b510 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
2b520 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
2b530 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
2b540 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
2b550 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63  e order..** ^A c
2b560 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
2b570 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
2b580 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c  the existing col
2b590 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61  lation-needed ca
2b5a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28  llback..**.** ^(
2b5b0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
2b5c0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
2b5d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b5e0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
2b5f0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
2b600 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
2b610 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2b620 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
2b630 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2b640 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
2b650 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2b660 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
2b670 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2b680 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
2b690 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2b6a0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
2b6b0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2b6c0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2b6d0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
2b6e0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
2b6f0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
2b700 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
2b710 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
2b720 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
2b730 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2b740 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
2b750 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
2b760 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b770 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  nce.)^.**.** The
2b780 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2b790 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74  on should regist
2b7a0 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63  er the desired c
2b7b0 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  ollation using.*
2b7c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2b7d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20  e_collation()], 
2b7e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b7f0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20  collation16()], 
2b800 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  or.** [sqlite3_c
2b810 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2b820 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  v2()]..*/.int sq
2b830 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b840 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
2b850 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
2b860 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2b870 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2b880 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
2b890 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2b8a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b8b0 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
2b8c0 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
2b8d0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2b8e0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2b8f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2b900 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
2b910 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20  HAS_CODEC./*.** 
2b920 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20  Specify the key 
2b930 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64  for an encrypted
2b940 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73   database.  This
2b950 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
2b960 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67  be.** called rig
2b970 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ht after sqlite3
2b980 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _open()..**.** T
2b990 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2b9a0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2b9b0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2b9c0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2b9d0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2b9e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2b9f0 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
2ba00 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ba10 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ba20 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2ba30 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2ba40 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2ba50 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
2ba60 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
2ba70 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
2ba80 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2ba90 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
2baa0 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
2bab0 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
2bac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
2bad0 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
2bae0 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
2baf0 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
2bb00 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
2bb10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
2bb20 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2bb30 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2bb40 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2bb50 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2bb60 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2bb70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b  .int sqlite3_rek
2bb80 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
2bb90 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2bba0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2bbb0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
2bbc0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2bbd0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
2bbe0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
2bbf0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
2bc00 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
2bc10 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
2bc20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
2bc30 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2bc40 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2bc50 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
2bc60 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
2bc70 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
2bc80 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
2bc90 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
2bca0 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
2bcb0 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
2bcc0 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
2bcd0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
2bce0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
2bcf0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
2bd00 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
2bd10 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
2bd20 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
2bd30 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
2bd40 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
2bd50 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2bd60 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2bd70 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
2bd80 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
2bd90 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
2bda0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
2bdb0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
2bdc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
2bdd0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
2bde0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
2bdf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2be00 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2be10 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2be20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2be30 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2be40 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2be50 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2be60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2be70 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2be80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
2be90 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
2bea0 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
2beb0 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
2bec0 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
2bed0 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
2bee0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
2bef0 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
2bf00 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
2bf10 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
2bf20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d  second. ^The num
2bf30 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2bf40 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
2bf50 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
2bf60 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
2bf70 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
2bf80 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2bf90 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
2bfa0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
2bfb0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
2bfc0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
2bfd0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
2bfe0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
2bff0 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
2c000 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2c010 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2c020 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
2c030 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
2c040 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
2c050 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
2c060 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2c070 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2c080 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2c090 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2c0a0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
2c0b0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
2c0c0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
2c0d0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
2c0e0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
2c0f0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
2c100 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
2c110 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
2c120 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
2c130 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
2c140 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
2c150 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
2c160 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2c170 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
2c180 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
2c190 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
2c1a0 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
2c1b0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
2c1c0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2c1d0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2c1e0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
2c1f0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
2c200 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
2c210 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
2c220 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2c230 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2c240 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
2c250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2c260 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
2c270 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2c280 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
2c290 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
2c2a0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
2c2b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
2c2c0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
2c2d0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
2c2e0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
2c2f0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
2c300 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
2c310 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
2c320 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
2c330 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2c340 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
2c350 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
2c360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
2c370 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2c380 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
2c390 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2c3a0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
2c3b0 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
2c3c0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2c3d0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2c3e0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
2c3f0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
2c400 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2c410 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
2c420 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
2c430 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
2c440 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2c450 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
2c460 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
2c470 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
2c480 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
2c490 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
2c4a0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
2c4b0 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
2c4c0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2c4d0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
2c4e0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
2c4f0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
2c500 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
2c510 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
2c520 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
2c530 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
2c540 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c550 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2c560 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
2c570 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
2c580 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
2c590 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
2c5a0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
2c5b0 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
2c5c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
2c5d0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
2c5e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2c5f0 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d  est For Auto-Com
2c600 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57  mit Mode.** KEYW
2c610 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
2c620 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54  t mode}.**.** ^T
2c630 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2c640 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
2c650 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
2c660 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
2c670 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
2c680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c690 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
2c6a0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
2c6b0 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
2c6c0 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69  ely.  ^Autocommi
2c6d0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
2c6e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74  default..** ^Aut
2c6f0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c700 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42  disabled by a [B
2c710 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
2c720 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2c730 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
2c740 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
2c750 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
2c760 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
2c770 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
2c780 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
2c790 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
2c7a0 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
2c7b0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
2c7c0 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
2c7d0 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
2c7e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
2c7f0 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2c800 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
2c810 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
2c820 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
2c830 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
2c840 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
2c850 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
2c860 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
2c870 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
2c880 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
2c890 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2c8a0 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
2c8b0 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
2c8c0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
2c8d0 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
2c8e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
2c8f0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
2c900 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
2c910 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
2c920 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2c930 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
2c940 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2c950 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
2c960 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2c970 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2c980 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
2c990 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
2c9a0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
2c9b0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
2c9c0 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
2c9d0 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
2c9e0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
2c9f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
2ca00 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
2ca10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
2ca20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca30 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
2ca40 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
2ca50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
2ca60 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
2ca70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ca80 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
2ca90 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
2caa0 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
2cab0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cac0 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
2cad0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2cae0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
2caf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cb00 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
2cb10 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
2cb20 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
2cb30 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
2cb40 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
2cb50 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c  st place..*/.sql
2cb60 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62  ite3 *sqlite3_db
2cb70 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
2cb80 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2cb90 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68  API3REF: Find th
2cba0 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20  e next prepared 
2cbb0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  statement.**.** 
2cbc0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2cbd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2cbe0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
2cbf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cc00 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
2cc10 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
2cc20 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2cc30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
2cc40 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e    ^If pStmt is N
2cc50 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ULL.** then this
2cc60 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cc70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cc80 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72  the first prepar
2cc90 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2cca0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2ccb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2ccc0 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49  nection pDb.  ^I
2ccd0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
2cce0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
2ccf0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
2cd00 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
2cd10 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
2cd20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
2cd30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cd40 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20  tion] pointer D 
2cd50 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  in a call to.** 
2cd60 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2cd70 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
2cd80 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
2cd90 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2cda0 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
2cdb0 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
2cdc0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
2cdd0 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  er..*/.sqlite3_s
2cde0 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
2cdf0 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
2ce00 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
2ce10 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2ce20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
2ce30 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
2ce40 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2ce50 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2ce60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2ce70 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2ce80 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2ce90 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
2cea0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
2ceb0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
2cec0 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d  saction is [COMM
2ced0 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e  IT | committed].
2cee0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2cef0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2cf00 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
2cf10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2cf20 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
2cf30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2cf40 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2cf50 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  den..** ^The sql
2cf60 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2cf70 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2cf80 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2cf90 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
2cfa0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2cfb0 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
2cfc0 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43  tion is [ROLLBAC
2cfd0 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d  K | rolled back]
2cfe0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2cff0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2d000 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2d010 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2d020 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
2d030 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2d040 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
2d050 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
2d060 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73  pArg argument is
2d070 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
2d080 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
2d090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
2d0a0 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
2d0b0 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
2d0c0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2d0d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
2d0e0 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
2d0f0 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
2d100 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2d110 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2d120 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69  (D,C,P) and sqli
2d130 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2d140 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
2d150 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65  ns.** return the
2d160 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
2d170 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2d180 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ll of the same f
2d190 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68  unction.** on th
2d1a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2d1b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
2d1c0 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74  or NULL for.** t
2d1d0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f  he first call fo
2d1e0 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20  r each function 
2d1f0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  on D..**.** The 
2d200 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
2d210 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2d220 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2d230 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2d240 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d250 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2d260 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
2d270 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
2d280 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
2d290 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d2a0 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
2d2b0 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
2d2c0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
2d2d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
2d2e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2d2f0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
2d300 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
2d310 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
2d320 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2d330 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
2d340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2d350 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2d360 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2d370 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2d380 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2d390 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2d3a0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2d3b0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2d3c0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  raph..**.** ^Reg
2d3d0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
2d3e0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2d3f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
2d400 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  **.** ^When the 
2d410 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
2d420 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74  back routine ret
2d430 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b  urns zero, the [
2d440 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61  COMMIT].** opera
2d450 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20  tion is allowed 
2d460 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d  to continue norm
2d470 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63  ally.  ^If the c
2d480 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65  ommit hook.** re
2d490 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
2d4a0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54  then the [COMMIT
2d4b0 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  ] is converted i
2d4c0 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  nto a [ROLLBACK]
2d4d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
2d4e0 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
2d4f0 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
2d500 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
2d510 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
2d520 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
2d530 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
2d540 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
2d550 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
2d560 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  ack..**.** ^For 
2d570 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
2d580 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
2d590 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
2d5a0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
2d5b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
2d5c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
2d5d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
2d5e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
2d5f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
2d600 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
2d610 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
2d620 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
2d630 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
2d640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
2d650 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
2d660 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
2d670 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2d680 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2d690 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
2d6a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
2d6b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  sed..**.** See a
2d6c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
2d6d0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20  _update_hook()] 
2d6e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f  interface..*/.vo
2d6f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
2d700 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
2d710 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
2d720 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
2d730 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2d740 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
2d750 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
2d760 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
2d770 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
2d780 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
2d790 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2d7a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
2d7b0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
2d7c0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2d7d0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2d7e0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
2d7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d800 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
2d810 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
2d820 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
2d830 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2d840 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
2d850 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
2d860 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  deleted..** ^Any
2d870 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2d880 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2d890 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2d8a0 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
2d8b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d8c0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
2d8d0 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  den..**.** ^The 
2d8e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2d8f0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
2d900 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
2d910 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a  invoke when a.**
2d920 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
2d930 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
2d940 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  eted..** ^The fi
2d950 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2d960 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2d970 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
2d980 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
2d990 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
2d9a0 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68  e_hook()..** ^Th
2d9b0 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
2d9c0 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  k argument is on
2d9d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
2d9e0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
2d9f0 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  LETE],.** or [SQ
2da00 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65  LITE_UPDATE], de
2da10 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
2da20 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61  peration that ca
2da30 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63  used the callbac
2da40 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  k.** to be invok
2da50 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  ed..** ^The thir
2da60 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
2da70 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
2da80 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
2da90 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
2daa0 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
2dab0 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
2dac0 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
2dad0 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66  d row..** ^The f
2dae0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
2daf0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2db00 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f  rowid] of the ro
2db10 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61  w..** ^In the ca
2db20 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c  se of an update,
2db30 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f   this is the [ro
2db40 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75  wid] after the u
2db50 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
2db60 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75  e..**.** ^(The u
2db70 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
2db80 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
2db90 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
2dba0 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
2dbb0 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
2dbc0 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
2dbd0 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29  lite_sequence).)
2dbe0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ^.**.** ^In the 
2dbf0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
2dc00 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61  tation, the upda
2dc10 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f  te hook.** is no
2dc20 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64  t invoked when d
2dc30 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20  uplication rows 
2dc40 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61  are deleted beca
2dc50 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e  use of an.** [ON
2dc60 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43   CONFLICT | ON C
2dc70 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d  ONFLICT REPLACE]
2dc80 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69   clause.  ^Nor i
2dc90 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  s the update hoo
2dca0 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65  k.** invoked whe
2dcb0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2dcc0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72  ed using the [tr
2dcd0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
2dce0 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63  ion]..** The exc
2dcf0 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20  eptions defined 
2dd00 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2dd10 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  h might change i
2dd20 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
2dd30 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
2dd40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74  .**.** The updat
2dd50 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74  e hook implement
2dd60 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2dd70 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2dd80 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2dd90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2dda0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2ddb0 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  ked the update h
2ddc0 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ook.  Any action
2ddd0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2dde0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2ddf0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2de00 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2de10 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2de20 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2de30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2de40 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2de50 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2de60 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
2de70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2de80 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
2de90 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
2dea0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
2deb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2dec0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
2ded0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
2dee0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
2def0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  aph..**.** ^The 
2df00 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2df10 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74  ook(D,C,P) funct
2df20 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ion.** returns t
2df30 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72  he P argument fr
2df40 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
2df50 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73  call.** on the s
2df60 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2df70 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20  nnection] D, or 
2df80 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20  NULL for.** the 
2df90 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e  first call on D.
2dfa0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
2dfb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
2dfc0 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
2dfd0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2dfe0 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
2dff0 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64  erfaces..*/.void
2e000 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   *sqlite3_update
2e010 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33  _hook(.  sqlite3
2e020 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2e030 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63  id *,int ,char c
2e040 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73  onst *,char cons
2e050 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  t *,sqlite3_int6
2e060 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a  4),.  void*.);..
2e070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e080 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
2e090 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43  e Shared Pager C
2e0a0 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ache.** KEYWORDS
2e0b0 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d  : {shared cache}
2e0c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2e0d0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
2e0e0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68   disables the sh
2e0f0 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  aring of the dat
2e100 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61  abase cache.** a
2e110 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73  nd schema data s
2e120 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65  tructures betwee
2e130 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
2e140 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74  ection | connect
2e150 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ions].** to the 
2e160 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53  same database. S
2e170 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
2e180 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2e190 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64  t is true.** and
2e1a0 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65   disabled if the
2e1b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c   argument is fal
2e1c0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63  se.)^.**.** ^Cac
2e1d0 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e  he sharing is en
2e1e0 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c  abled and disabl
2e1f0 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65  ed for an entire
2e200 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69   process..** Thi
2e210 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
2e220 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
2e230 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
2e240 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
2e250 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
2e260 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
2e270 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
2e280 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
2e290 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tely..**.** ^(Th
2e2a0 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
2e2b0 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
2e2c0 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
2e2d0 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
2e2e0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
2e2f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2e300 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2e310 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2e320 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
2e330 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
2e340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
2e350 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
2e360 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
2e370 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
2e380 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
2e390 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29  ey were opened.)
2e3a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ^.**.** ^(This r
2e3b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
2e3c0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
2e3d0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
2e3e0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
2e3f0 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ed.** successful
2e400 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
2e410 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2e420 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a   otherwise.)^.**
2e430 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68  .** ^Shared cach
2e440 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2e450 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
2e460 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
2e470 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
2e480 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2e490 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2e4a0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
2e4b0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
2e4c0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
2e4d0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
2e4e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
2e4f0 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
2e500 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a  -Cache Mode].*/.
2e510 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
2e520 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
2e530 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2e540 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
2e550 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
2e560 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
2e570 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2e580 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
2e590 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
2e5a0 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
2e5b0 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
2e5c0 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
2e5d0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
2e5e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
2e5f0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
2e600 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
2e610 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
2e620 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
2e630 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
2e640 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
2e650 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
2e660 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
2e670 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
2e680 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2e690 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
2e6a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
2e6b0 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
2e6c0 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
2e6d0 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
2e6e0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
2e6f0 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  uested..*/.int s
2e700 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e710 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
2e720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
2e730 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
2e740 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
2e750 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
2e760 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e  _heap_limit() in
2e770 74 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61  terface places a
2e780 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a   "soft" limit.**
2e790 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f   on the amount o
2e7a0 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68  f heap memory th
2e7b0 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61  at may be alloca
2e7c0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2e7d0 2a 20 5e 49 66 20 61 6e 20 69 6e 74 65 72 6e 61  * ^If an interna
2e7e0 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  l allocation is 
2e7f0 72 65 71 75 65 73 74 65 64 20 74 68 61 74 20 77  requested that w
2e800 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2e810 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  ** soft heap lim
2e820 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  it, [sqlite3_rel
2e830 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69  ease_memory()] i
2e840 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72  s invoked one or
2e850 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74  .** more times t
2e860 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73  o free up some s
2e870 70 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20  pace before the 
2e880 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65  allocation is pe
2e890 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rformed..**.** ^
2e8a0 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63 61 6c  The limit is cal
2e8b0 6c 65 64 20 22 73 6f 66 74 22 20 62 65 63 61 75  led "soft" becau
2e8c0 73 65 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72  se if [sqlite3_r
2e8d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2e8e0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20  .** cannot free 
2e8f0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
2e900 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65  y to prevent the
2e910 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e   limit from bein
2e920 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74  g exceeded,.** t
2e930 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  he memory is all
2e940 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e  ocated anyway an
2e950 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70  d the current op
2e960 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
2e970 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  ..**.** ^A negat
2e980 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75  ive or zero valu
2e990 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68  e for N means th
2e9a0 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73  at there is no s
2e9b0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61  oft heap limit a
2e9c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  nd.** [sqlite3_r
2e9d0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2e9e0 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61   will only be ca
2e9f0 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79  lled when memory
2ea00 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
2ea10 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 76  * ^The default v
2ea20 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66  alue for the sof
2ea30 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
2ea40 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51  zero..**.** ^(SQ
2ea50 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73  Lite makes a bes
2ea60 74 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f  t effort to hono
2ea70 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2ea80 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66  limit..** But if
2ea90 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2eaa0 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68  imit cannot be h
2eab0 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f  onored, executio
2eac0 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e  n will.** contin
2ead0 75 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72  ue without error
2eae0 20 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e   or notification
2eaf0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 77 68 79  .)^  This is why
2eb00 20 74 68 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a   the limit is.**
2eb10 20 63 61 6c 6c 65 64 20 61 20 22 73 6f 66 74 22   called a "soft"
2eb20 20 6c 69 6d 69 74 2e 20 20 49 74 20 69 73 20 61   limit.  It is a
2eb30 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a  dvisory only..**
2eb40 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
2eb50 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2eb60 30 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  0, this routine 
2eb70 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69 6e 65 64  only constrained
2eb80 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2eb90 6c 6c 6f 63 61 74 65 64 20 62 79 20 61 20 73 69  llocated by a si
2eba0 6e 67 6c 65 20 74 68 72 65 61 64 20 2d 20 74 68  ngle thread - th
2ebb0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2ebc0 20 77 68 69 63 68 20 74 68 69 73 20 72 6f 75 74   which this rout
2ebd0 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65  ine.** runs.  Be
2ebe0 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
2ebf0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2ec00 30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  0, the soft heap
2ec10 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70   limit is.** app
2ec20 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74 68 72 65  lied to all thre
2ec30 61 64 73 2e 20 54 68 65 20 76 61 6c 75 65 20 73  ads. The value s
2ec40 70 65 63 69 66 69 65 64 20 66 6f 72 20 74 68 65  pecified for the
2ec50 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2ec60 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70 65 72 20  .** is an upper 
2ec70 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74  bound on the tot
2ec80 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2ec90 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72  tion for all thr
2eca0 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73  eads. In.** vers
2ecb0 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65 72 65 20  ion 3.5.0 there 
2ecc0 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20  is no mechanism 
2ecd0 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20 74 68 65  for limiting the
2ece0 20 68 65 61 70 20 75 73 61 67 65 20 66 6f 72 0a   heap usage for.
2ecf0 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c 20 74 68  ** individual th
2ed00 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  reads..*/.void s
2ed10 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2ed20 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
2ed30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
2ed40 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
2ed50 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
2ed60 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
2ed70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2ed80 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
2ed90 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
2eda0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
2edb0 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
2edc0 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
2edd0 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
2ede0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2edf0 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
2ee00 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
2ee10 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2ee20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
2ee30 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
2ee40 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
2ee50 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2ee60 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
2ee70 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
2ee80 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
2ee90 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
2eea0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
2eeb0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
2eec0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
2eed0 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
2eee0 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
2eef0 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
2ef00 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
2ef10 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
2ef20 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
2ef30 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2ef40 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
2ef50 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
2ef60 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
2ef70 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
2ef80 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2ef90 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
2efa0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
2efb0 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
2efc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
2efd0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
2efe0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
2eff0 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
2f000 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
2f010 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
2f020 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
2f030 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2f040 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
2f050 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
2f060 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
2f070 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
2f080 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
2f090 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
2f0a0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
2f0b0 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
2f0c0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2f0d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
2f0e0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
2f0f0 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
2f100 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
2f110 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
2f120 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
2f130 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
2f140 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
2f150 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
2f160 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2f170 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2f180 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
2f190 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
2f1a0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
2f1b0 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
2f1c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
2f1d0 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2f1e0 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
2f1f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
2f200 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
2f210 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
2f220 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
2f230 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
2f240 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
2f250 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
2f260 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
2f270 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
2f280 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
2f290 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
2f2a0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2f2b0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
2f2c0 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
2f2d0 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
2f2e0 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
2f2f0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
2f300 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
2f310 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
2f320 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2f330 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
2f340 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
2f350 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2f360 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
2f370 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
2f380 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
2f390 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
2f3a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f3b0 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
2f3c0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
2f3d0 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
2f3e0 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
2f3f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2f400 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
2f410 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
2f420 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
2f430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2f440 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
2f450 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
2f460 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
2f470 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
2f480 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
2f490 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
2f4a0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
2f4b0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2f4c0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
2f4d0 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
2f4e0 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
2f4f0 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
2f500 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
2f510 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
2f520 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
2f530 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
2f540 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2f550 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
2f560 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
2f570 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
2f580 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
2f590 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
2f5a0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
2f5b0 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
2f5c0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
2f5d0 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
2f5e0 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
2f5f0 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
2f600 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
2f610 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
2f620 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
2f630 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
2f640 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
2f650 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
2f660 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
2f670 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2f680 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
2f690 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
2f6a0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
2f6b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
2f6c0 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
2f6d0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2f6e0 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
2f6f0 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
2f700 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
2f710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f720 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
2f730 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
2f740 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
2f750 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
2f760 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
2f770 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
2f780 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
2f790 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
2f7a0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
2f7b0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
2f7c0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
2f7d0 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2f7e0 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
2f7f0 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
2f800 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2f810 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
2f820 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
2f830 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2f840 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
2f850 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
2f860 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
2f870 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
2f880 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
2f890 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
2f8a0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
2f8b0 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
2f8c0 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
2f8d0 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
2f8e0 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
2f8f0 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
2f900 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
2f910 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
2f920 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
2f930 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
2f940 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
2f950 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
2f960 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2f970 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
2f980 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
2f990 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
2f9a0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
2f9b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2f9c0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2f9d0 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
2f9e0 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
2f9f0 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
2fa00 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2fa10 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
2fa20 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
2fa30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fa40 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
2fa50 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
2fa60 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
2fa70 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
2fa80 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
2fa90 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
2faa0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
2fab0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2fac0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2fad0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
2fae0 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
2faf0 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
2fb00 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
2fb10 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
2fb20 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
2fb30 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
2fb40 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
2fb50 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
2fb60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2fb70 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
2fb80 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
2fb90 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
2fba0 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
2fbb0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2fbc0 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
2fbd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
2fbe0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2fbf0 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
2fc00 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
2fc10 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
2fc20 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
2fc30 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
2fc40 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
2fc50 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
2fc60 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2fc70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
2fc80 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
2fc90 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
2fca0 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
2fcb0 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
2fcc0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
2fcd0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2fce0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
2fcf0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
2fd00 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
2fd10 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
2fd20 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2fd30 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2fd40 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
2fd50 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
2fd60 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
2fd70 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2fd80 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
2fd90 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
2fda0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
2fdb0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
2fdc0 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
2fdd0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
2fde0 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
2fdf0 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
2fe00 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
2fe10 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2fe20 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
2fe30 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
2fe40 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
2fe50 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
2fe60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe70 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
2fe80 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
2fe90 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
2fea0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
2feb0 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
2fec0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2fed0 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
2fee0 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
2fef0 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
2ff00 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
2ff10 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
2ff20 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
2ff30 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
2ff40 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
2ff50 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2ff60 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
2ff70 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
2ff80 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
2ff90 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
2ffa0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
2ffb0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2ffc0 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
2ffd0 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
2ffe0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2fff0 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
30000 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
30010 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
30020 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
30030 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
30040 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
30050 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
30060 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
30070 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
30080 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
30090 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
300a0 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
300b0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
300c0 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
300d0 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
300e0 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
300f0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
30100 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
30110 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
30120 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
30130 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
30140 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
30150 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
30160 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
30170 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
30180 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
30190 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
301a0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
301b0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
301c0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
301d0 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41  matically Load A
301e0 6e 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a  n Extensions.**.
301f0 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 63 61 6e  ** ^This API can
30200 20 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70   be invoked at p
30210 72 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69  rogram startup i
30220 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73  n order to regis
30230 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
30240 72 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69  re statically li
30250 6e 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20  nked extensions 
30260 74 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61  that will be ava
30270 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c  ilable.** to all
30280 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
30290 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a  onnections]..**.
302a0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
302b0 65 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e 74  e stores a point
302c0 65 72 20 74 6f 20 74 68 65 20 65 78 74 65 6e 73  er to the extens
302d0 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  ion entry point.
302e0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74  ** in an array t
302f0 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65 64 20  hat is obtained 
30300 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
30310 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 61 74 20 6d  lloc()].  That m
30320 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c  emory.** is deal
30330 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69  located by [sqli
30340 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
30350 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a  xtension()].)^.*
30360 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
30370 69 6f 6e 20 72 65 67 69 73 74 65 72 73 20 61 6e  ion registers an
30380 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
30390 20 70 6f 69 6e 74 20 74 68 61 74 20 69 73 0a 2a   point that is.*
303a0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
303b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
303c0 20 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65   a new [database
303d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
303e0 69 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20  is opened using 
303f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
30400 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
30410 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  6()],.** or [sql
30420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
30430 0a 2a 2a 20 5e 44 75 70 6c 69 63 61 74 65 20 65  .** ^Duplicate e
30440 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20 64 65  xtensions are de
30450 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e  tected so callin
30460 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  g this routine.*
30470 2a 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  * multiple times
30480 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 65   with the same e
30490 78 74 65 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d  xtension is harm
304a0 6c 65 73 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61  less..** ^Automa
304b0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
304c0 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
304d0 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20  threads..*/.int 
304e0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
304f0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
30500 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
30510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30520 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
30530 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
30540 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ading.**.** ^(Th
30550 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
30560 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
30570 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61  sly registered a
30580 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65  utomatic.** exte
30590 6e 73 69 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65  nsions. It undoe
305a0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
305b0 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71  all prior.** [sq
305c0 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e  lite3_auto_exten
305d0 73 69 6f 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e  sion()] calls.)^
305e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
305f0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
30600 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
30610 6f 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61  ons in all threa
30620 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
30630 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
30640 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
30650 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
30660 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
30670 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
30680 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
30690 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
306a0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
306b0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
306c0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
306d0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
306e0 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
306f0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
30700 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
30710 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
30720 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
30730 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
30740 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
30750 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
30760 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
30770 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
30780 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
30790 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
307a0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
307b0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
307c0 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
307d0 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
307e0 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
307f0 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
30800 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
30810 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
30820 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30830 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
30840 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
30850 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
30860 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
30870 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
30880 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
30890 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
308a0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
308b0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
308c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
308d0 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
308e0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
308f0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
30900 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30910 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
30920 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
30930 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20  imes called a a 
30940 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
30950 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
30960 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
30970 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
30980 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
30990 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
309a0 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
309b0 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
309c0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
309d0 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61  ** ^A virtual ta
309e0 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72  ble module is cr
309f0 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67  eated by filling
30a00 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74   in a persistent
30a10 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
30a20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61  this structure a
30a30 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69  nd passing a poi
30a40 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73  nter to that ins
30a50 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c  tance.** to [sql
30a60 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
30a70 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  le()] or [sqlite
30a80 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
30a90 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  v2()]..** ^The r
30aa0 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61  egistration rema
30ab0 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  ins valid until 
30ac0 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20 62  it is replaced b
30ad0 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  y a different.**
30ae0 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c   module or until
30af0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30b00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65  onnection] close
30b10 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a  s.  The content.
30b20 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ** of this struc
30b30 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68  ture must not ch
30b40 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69 73  ange while it is
30b50 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
30b60 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65  .** any database
30b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a   connection..*/.
30b80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
30b90 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56  odule {.  int iV
30ba0 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
30bb0 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65 33  xCreate)(sqlite3
30bc0 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
30bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
30be0 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
30bf0 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
30c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
30c10 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
30c20 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
30c30 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29   int (*xConnect)
30c40 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
30c50 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
30c60 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30c70 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
30c80 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
30c90 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
30ca0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
30cb0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
30cc0 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74  BestIndex)(sqlit
30cd0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
30ce0 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
30cf0 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  fo*);.  int (*xD
30d00 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  isconnect)(sqlit
30d10 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
30d20 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f  .  int (*xDestro
30d30 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  y)(sqlite3_vtab 
30d40 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30d50 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
30d60 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
30d70 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
30d80 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20   **ppCursor);.  
30d90 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
30da0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30db0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  r*);.  int (*xFi
30dc0 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
30dd0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
30de0 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
30df0 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
30e00 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
30e10 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61  argc, sqlite3_va
30e20 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69  lue **argv);.  i
30e30 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69  nt (*xNext)(sqli
30e40 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30e50 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29  );.  int (*xEof)
30e60 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30e70 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
30e80 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33  xColumn)(sqlite3
30e90 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
30ea0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30eb0 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
30ec0 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76  Rowid)(sqlite3_v
30ed0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
30ee0 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77  ite3_int64 *pRow
30ef0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70  id);.  int (*xUp
30f00 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74  date)(sqlite3_vt
30f10 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  ab *, int, sqlit
30f20 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c  e3_value **, sql
30f30 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20  ite3_int64 *);. 
30f40 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73   int (*xBegin)(s
30f50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
30f60 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ab);.  int (*xSy
30f70 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  nc)(sqlite3_vtab
30f80 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
30f90 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74  (*xCommit)(sqlit
30fa0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
30fb0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61  .  int (*xRollba
30fc0 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ck)(sqlite3_vtab
30fd0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
30fe0 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29  (*xFindFunction)
30ff0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31000 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20  Vtab, int nArg, 
31010 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
31020 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  e,.             
31030 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 28            void (
31040 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65  **pxFunc)(sqlite
31050 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31060 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31070 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
31080 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70          void **p
31090 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
310a0 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  Rename)(sqlite3_
310b0 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e  vtab *pVtab, con
310c0 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a  st char *zNew);.
310d0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
310e0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
310f0 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72  e Indexing Infor
31100 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52  mation.** KEYWOR
31110 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
31120 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65  x_info.**.** The
31130 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31140 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
31150 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
31160 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
31170 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
31180 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
31190 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
311a0 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64  om the [xBestInd
311b0 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  ex].** method of
311c0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
311d0 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20  e module].  The 
311e0 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
311f0 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
31200 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
31210 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
31220 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
31230 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
31240 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
31250 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
31260 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
31270 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69   ^(The aConstrai
31280 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72  nt[] array recor
31290 64 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ds WHERE clause 
312a0 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74  constraints of t
312b0 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c  he form:.**.** <
312c0 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78  pre>column OP ex
312d0 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77  pr</pre>.**.** w
312e0 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c  here OP is =, &l
312f0 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c  t;, &lt;=, &gt;,
31300 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28   or &gt;=.)^  ^(
31310 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f  The particular o
31320 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74  perator is.** st
31330 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61  ored in aConstra
31340 69 6e 74 5b 5d 2e 6f 70 2e 29 5e 20 20 5e 28 54  int[].op.)^  ^(T
31350 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
31360 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
31370 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
31380 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20  nt[].iColumn.)^ 
31390 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d   ^(aConstraint[]
313a0 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
313b0 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
313c0 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
313d0 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
313e0 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
313f0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
31400 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
31410 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
31420 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  nnot.)^.**.** ^T
31430 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
31440 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
31450 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
31460 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
31470 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
31480 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
31490 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
314a0 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
314b0 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
314c0 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
314d0 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
314e0 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
314f0 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
31500 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61  sible..** ^The a
31510 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
31520 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ay only reports 
31530 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
31540 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72  ms that are.** r
31550 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70  elevant to the p
31560 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
31570 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
31580 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  eried..**.** ^In
31590 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
315a0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
315b0 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
315c0 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
315d0 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f  ^Each term of aO
315e0 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61  rderBy records a
315f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f   column of the O
31600 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a  RDER BY clause..
31610 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74  **.** The [xBest
31620 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75  Index] method mu
31630 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
31640 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
31650 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
31660 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
31670 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
31680 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72  xFilter.  ^If ar
31690 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
316a0 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
316b0 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
316c0 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
316d0 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
316e0 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
316f0 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
31700 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
31710 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73  rgv.  ^(If aCons
31720 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
31730 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
31740 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
31750 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
31760 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
31770 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
31780 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
31790 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
317a0 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a  in by SQLite.)^.
317b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75  **.** ^The idxNu
317c0 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
317d0 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
317e0 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
317f0 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72   the.** [xFilter
31800 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73  ] method..** ^[s
31810 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
31820 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69  s used to free i
31830 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c  dxPtr if and onl
31840 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72  y if.** needToFr
31850 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
31860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64  ..**.** ^The ord
31870 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61  erByConsumed mea
31880 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66  ns that output f
31890 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78  rom [xFilter]/[x
318a0 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72  Next] will occur
318b0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
318c0 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
318d0 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
318e0 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
318f0 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
31900 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
31910 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
31920 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
31930 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
31940 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
31950 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
31960 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
31970 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
31980 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
31990 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
319a0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
319b0 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
319c0 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
319d0 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
319e0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
319f0 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
31a00 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
31a10 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
31a20 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
31a30 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
31a40 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74   int nConstraint
31a50 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ;           /* N
31a60 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
31a70 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
31a80 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
31a90 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
31aa0 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20  aint {.     int 
31ab0 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
31ac0 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
31ad0 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  on left-hand sid
31ae0 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20  e of constraint 
31af0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
31b00 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20   char op;       
31b10 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20    /* Constraint 
31b20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20  operator */.    
31b30 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75   unsigned char u
31b40 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72  sable;     /* Tr
31b50 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74  ue if this const
31b60 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20  raint is usable 
31b70 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72  */.     int iTer
31b80 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
31b90 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
31ba0 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
31bb0 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
31bc0 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
31bd0 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20  int;            
31be0 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52  /* Table of WHER
31bf0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
31c00 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f  ints */.  int nO
31c10 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
31c20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
31c30 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
31c40 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
31c50 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
31c60 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
31c70 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
31c80 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
31c90 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
31ca0 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
31cb0 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
31cc0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
31cd0 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
31ce0 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61  r ASC. */.  } *a
31cf0 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
31d00 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
31d10 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
31d20 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
31d30 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
31d40 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
31d50 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
31d60 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
31d70 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
31d80 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
31d90 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
31da0 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
31db0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
31dc0 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
31dd0 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
31de0 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
31df0 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
31e00 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
31e10 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
31e20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
31e30 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
31e40 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
31e50 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
31e60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31e70 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
31e80 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
31e90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
31ea0 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
31eb0 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
31ec0 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
31ed0 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
31ee0 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
31ef0 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
31f00 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
31f10 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
31f20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
31f30 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
31f40 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
31f50 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
31f60 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
31f70 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66  index */.};.#def
31f80 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31f90 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
31fa0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
31fb0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
31fc0 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
31fd0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31fe0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
31ff0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
32000 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32010 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
32020 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
32030 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
32040 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
32050 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32060 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
32070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32080 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
32090 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
320a0 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  ntation.**.** ^T
320b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
320c0 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  e used to regist
320d0 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  er a new [virtua
320e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
320f0 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65  name..** ^Module
32100 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must be r
32110 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65  egistered before
32120 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e  .** creating a n
32130 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
32140 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64  e] using the mod
32150 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75  ule and before u
32160 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69  sing a.** preexi
32170 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74  sting [virtual t
32180 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  able] for the mo
32190 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dule..**.** ^The
321a0 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20   module name is 
321b0 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68  registered on th
321c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
321d0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
321e0 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
321f0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  t parameter.  ^T
32200 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
32210 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
32220 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
32230 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
32240 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
32250 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
32260 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  o.** the impleme
32270 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ntation of the [
32280 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32290 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f  dule].   ^The fo
322a0 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  urth.** paramete
322b0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
322c0 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f  y client data po
322d0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
322e0 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
322f0 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74  into the [xCreat
32300 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
32310 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  ] methods of the
32320 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
32330 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20  odule.** when a 
32340 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
32350 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72  e is be being cr
32360 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69  eated or reiniti
32370 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  alized..**.** ^T
32380 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
32390 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e  e_module_v2() in
323a0 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69  terface has a fi
323b0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68  fth parameter wh
323c0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
323d0 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
323e0 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69  tor for the pCli
323f0 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74  entData.  ^SQLit
32400 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65  e will.** invoke
32410 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
32420 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20  function (if it 
32430 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65  is not NULL) whe
32440 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c  n SQLite.** no l
32450 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20  onger needs the 
32460 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e  pClientData poin
32470 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ter.  ^The sqlit
32480 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32490 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
324a0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
324b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
324c0 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68  module_v2() with
324d0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72   a NULL.** destr
324e0 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  uctor..*/.int sq
324f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
32500 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ule(.  sqlite3 *
32510 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
32520 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
32530 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
32540 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
32550 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
32560 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
32570 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
32580 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
32590 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
325a0 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
325b0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
325c0 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
325d0 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f  tData          /
325e0 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
325f0 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
32600 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ct */.);.int sql
32610 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32620 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
32630 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
32640 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
32650 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
32660 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
32670 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
32680 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
32690 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
326a0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
326b0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
326c0 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
326d0 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
326e0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
326f0 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20  entData,        
32700 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
32710 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
32720 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
32730 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
32740 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
32750 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
32760 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
32770 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
32780 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65  l Table Instance
32790 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
327a0 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
327b0 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  b.**.** Every [v
327c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
327d0 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
327e0 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
327f0 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f  ass.** of this o
32800 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69 62  bject to describ
32810 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
32820 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68  nstance.** of th
32830 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
32840 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  ].  Each subclas
32850 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
32860 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
32870 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
32880 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
32890 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
328a0 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
328b0 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
328c0 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
328d0 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
328e0 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
328f0 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
32900 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
32910 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  ^Virtual tables 
32920 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
32930 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
32940 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
32950 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
32960 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
32970 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a  _mprintf()] to z
32980 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74  ErrMsg.  The met
32990 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61  hod should.** ta
329a0 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79  ke care that any
329b0 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73   prior string is
329c0 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c   freed by a call
329d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
329e0 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  e()].** prior to
329f0 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77   assigning a new
32a00 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d   string to zErrM
32a10 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20  sg.  ^After the 
32a20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
32a30 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
32a40 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
32a50 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
32a60 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
32a70 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
32a80 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
32a90 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
32aa0 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
32ab0 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f  ll be zeroed..*/
32ac0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
32ad0 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
32ae0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
32af0 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
32b00 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
32b10 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
32b20 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
32b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b40 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20     /* NO LONGER 
32b50 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a  USED */.  char *
32b60 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
32b70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
32b80 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
32b90 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
32ba0 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
32bb0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
32bc0 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
32bd0 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
32be0 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
32bf0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
32c00 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
32c10 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a  e Cursor Object.
32c20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
32c30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
32c40 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
32c50 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76  cursor}.**.** Ev
32c60 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
32c70 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
32c80 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
32c90 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
32ca0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  .** following st
32cb0 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72  ructure to descr
32cc0 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
32cd0 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a   point into the.
32ce0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
32cf0 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  e] and are used.
32d00 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
32d10 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
32d20 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
32d30 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
32d40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
32d50 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20  _module.xOpen | 
32d60 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  xOpen] method of
32d70 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
32d80 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a  are destroyed.**
32d90 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
32da0 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c  _module.xClose |
32db0 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e   xClose] method.
32dc0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 75 73    Cursors are us
32dd0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46  ed.** by the [xF
32de0 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c  ilter], [xNext],
32df0 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d   [xEof], [xColum
32e00 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d  n], and [xRowid]
32e10 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74   methods.** of t
32e20 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
32e30 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
32e40 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69  tation will defi
32e50 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  ne.** the conten
32e60 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74  t of a cursor st
32e70 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20  ructure to suit 
32e80 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a  its own needs..*
32e90 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63  *.** This superc
32ea0 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f  lass exists in o
32eb0 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66  rder to define f
32ec0 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72  ields of the cur
32ed0 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  sor that.** are 
32ee0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d  common to all im
32ef0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
32f00 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
32f10 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20  _vtab_cursor {. 
32f20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70   sqlite3_vtab *p
32f30 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69  Vtab;      /* Vi
32f40 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74  rtual table of t
32f50 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20  his cursor */.  
32f60 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
32f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32f80 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
32f90 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
32fa0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
32fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
32fc0 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20  lare The Schema 
32fd0 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  Of A Virtual Tab
32fe0 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78  le.**.** ^The [x
32ff0 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
33000 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
33010 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  f a.** [virtual 
33020 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61  table module] ca
33030 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ll this interfac
33040 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20  e.** to declare 
33050 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20  the format (the 
33060 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
33070 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  pes of the colum
33080 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69  ns) of.** the vi
33090 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65  rtual tables the
330a0 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a  y implement..*/.
330b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
330c0 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
330d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
330e0 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  SQL);../*.** CAP
330f0 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
33100 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
33110 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
33120 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74  *.** ^(Virtual t
33130 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
33140 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
33150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
33160 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
33170 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75  ing the [xFindFu
33180 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f  nction] method o
33190 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
331a0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a  able module].  .
331b0 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  ** But global ve
331c0 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
331d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
331e0 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
331f0 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
33200 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
33210 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
33220 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
33230 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
33240 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
33250 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
33260 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
33270 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
33280 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
33290 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
332a0 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
332b0 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
332c0 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29  ion is created.)
332d0 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ^  ^The implemen
332e0 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
332f0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
33300 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
33310 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
33320 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
33330 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
33340 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
33350 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
33360 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
33370 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
33380 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66   a placeholder f
33390 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e  unction that can
333a0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a   be overloaded.*
333b0 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20  * by a [virtual 
333c0 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  table]..*/.int s
333d0 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
333e0 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
333f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
33400 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
33410 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
33420 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
33430 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
33440 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
33450 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
33460 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
33470 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
33480 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
33490 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
334a0 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
334b0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
334c0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
334d0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
334e0 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
334f0 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
33500 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
33510 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
33520 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
33530 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
33540 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
33550 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
33560 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
33570 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
33580 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
33590 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
335a0 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
335b0 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
335c0 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
335d0 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
335e0 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
335f0 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  OB.** KEYWORDS: 
33600 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42  {BLOB handle} {B
33610 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a  LOB handles}.**.
33620 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
33630 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
33640 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
33650 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a   BLOB on which.*
33660 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
33670 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
33680 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e  al BLOB I/O] can
33690 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   be performed..*
336a0 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  * ^Objects of th
336b0 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
336c0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
336d0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  blob_open()].** 
336e0 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
336f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
33700 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  lose()]..** ^The
33710 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
33720 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
33730 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
33740 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
33750 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
33760 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
33770 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
33780 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e  f the BLOB..** ^
33790 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
337a0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
337b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
337c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
337d0 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
337e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
337f0 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
33800 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
33810 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
33820 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
33830 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
33840 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
33850 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
33860 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
33870 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
33880 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
33890 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
338a0 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
338b0 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
338c0 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
338d0 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
338e0 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
338f0 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
33900 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
33910 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
33920 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
33930 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
33940 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
33950 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
33960 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
33970 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
33980 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f  en the BLOB is o
33990 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a  pened for read.*
339a0 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  * and write acce
339b0 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65  ss. ^If it is ze
339c0 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  ro, the BLOB is 
339d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
339e0 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69  access..** ^It i
339f0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
33a00 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
33a10 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
33a20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d  an index or prim
33a30 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20  ary .** key for 
33a40 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f  writing. ^If [fo
33a50 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
33a60 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c  aints] are enabl
33a70 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f  ed, it is .** no
33a80 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
33a90 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
33aa0 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63   is part of a [c
33ab0 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72  hild key] for wr
33ac0 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  iting..**.** ^No
33ad0 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61  te that the data
33ae0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74  base name is not
33af0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68   the filename th
33b00 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  at contains.** t
33b10 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20  he database but 
33b20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f  rather the symbo
33b30 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  lic name of the 
33b40 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a  database that.**
33b50 20 61 70 70 65 61 72 73 20 61 66 74 65 72 20 74   appears after t
33b60 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68  he AS keyword wh
33b70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
33b80 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
33b90 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
33ba0 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61  ^For the main da
33bb0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
33bc0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
33bd0 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f  s "main"..** ^Fo
33be0 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  r TEMP tables, t
33bf0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
33c00 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
33c10 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
33c20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
33c30 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
33c40 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
33c50 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
33c60 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
33c70 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
33c80 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
33c90 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73  d and *ppBlob is
33ca0 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20   set.** to be a 
33cb0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a  null pointer.)^.
33cc0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
33cd0 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61  n sets the [data
33ce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33cf0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
33d00 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73  message.** acces
33d10 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
33d20 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e  e3_errcode()] an
33d30 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
33d40 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64  g()] and related
33d50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e  .** functions. ^
33d60 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a 70  Note that the *p
33d70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69  pBlob variable i
33d80 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c  s always initial
33d90 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79  ized in a.** way
33da0 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73   that makes it s
33db0 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73  afe to invoke [s
33dc0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
33dd0 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a  e()] on *ppBlob.
33de0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
33df0 20 74 68 65 20 73 75 63 63 65 73 73 20 6f 72 20   the success or 
33e00 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20  failure of this 
33e10 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e  routine..**.** ^
33e20 28 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74  (If the row that
33e30 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70   a BLOB handle p
33e40 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69  oints to is modi
33e50 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55  fied by an.** [U
33e60 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
33e70 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46  , or by [ON CONF
33e80 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63  LICT] side-effec
33e90 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42  ts.** then the B
33ea0 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61  LOB handle is ma
33eb0 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64  rked as "expired
33ec0 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72  "..** This is tr
33ed0 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  ue if any column
33ee0 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63   of the row is c
33ef0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63  hanged, even a c
33f00 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74  olumn.** other t
33f10 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20  han the one the 
33f20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f  BLOB handle is o
33f30 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61  pen on.)^.** ^Ca
33f40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
33f50 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
33f60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
33f70 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61  rite()] for.** a
33f80 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61   expired BLOB ha
33f90 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61  ndle fail with a
33fa0 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  n return code of
33fb0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
33fc0 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72  .** ^(Changes wr
33fd0 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
33fe0 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
33ff0 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
34000 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62   not.** rolled b
34010 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72  ack by the expir
34020 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f  ation of the BLO
34030 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73  B.  Such changes
34040 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
34050 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68  .** commit if th
34060 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  e transaction co
34070 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
34080 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  etion.)^.**.** ^
34090 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
340a0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
340b0 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65  nterface to dete
340c0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f  rmine the size o
340d0 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20  f.** the opened 
340e0 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65  blob.  ^The size
340f0 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e   of a blob may n
34100 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ot be changed by
34110 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
34120 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50  ce.  Use the [UP
34130 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  DATE] SQL comman
34140 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
34150 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f  size of a.** blo
34160 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  b..**.** ^The [s
34170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
34180 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c  blob()] and [sql
34190 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
341a0 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63  blob()] interfac
341b0 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75  es.** and the bu
341c0 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62  ilt-in [zeroblob
341d0 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  ] SQL function c
341e0 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64  an be used, if d
341f0 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72  esired,.** to cr
34200 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a  eate an empty, z
34210 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20  ero-filled blob 
34220 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64  in which to read
34230 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a   or write using.
34240 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
34250 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  e..**.** To avoi
34260 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61  d a resource lea
34270 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42  k, every open [B
34280 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75  LOB handle] shou
34290 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ld eventually.**
342a0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20   be released by 
342b0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
342c0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
342d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
342e0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
342f0 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
34300 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
34310 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
34320 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34330 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
34340 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
34350 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
34360 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
34370 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
34380 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
34390 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
343a0 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e   ^Closes an open
343b0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
343c0 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61  **.** ^Closing a
343d0 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
343e0 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
343f0 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
34400 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
34410 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
34420 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
34430 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34440 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
34450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34460 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
34470 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e  mmit mode]..** ^
34480 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
34490 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
344a0 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
344b0 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
344c0 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
344d0 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
344e0 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a   they will fit..
344f0 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20  **.** ^(Closing 
34500 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66  the BLOB often f
34510 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65  orces the change
34520 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b  s.** out to disk
34530 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49   and so if any I
34540 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c  /O errors occur,
34550 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c   they will likel
34560 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68  y occur.** at th
34570 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  e time when the 
34580 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20  BLOB is closed. 
34590 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74   Any errors that
345a0 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a   occur during.**
345b0 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70   closing are rep
345c0 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a  orted as a non-z
345d0 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ero return value
345e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  .)^.**.** ^(The 
345f0 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
34600 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
34610 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
34620 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
34630 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
34640 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
34650 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a  l closed.)^.**.*
34660 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
34670 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e  routine with a n
34680 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63  ull pointer (suc
34690 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65  h as would be re
346a0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66  turned.** by a f
346b0 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
346c0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
346d0 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
346e0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
346f0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c   sqlite3_blob_cl
34700 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ose(sqlite3_blob
34710 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
34720 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
34730 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e   Size Of An Open
34740 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   BLOB.**.** ^Ret
34750 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
34760 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
34770 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
34780 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
34790 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
347a0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
347b0 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
347c0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65  .  ^The.** incre
347d0 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20  mental blob I/O 
347e0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c  routines can onl
347f0 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72  y read or overwr
34800 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a  iting existing.*
34810 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20  * blob content; 
34820 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e  they cannot chan
34830 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
34840 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   blob..**.** Thi
34850 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
34860 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
34870 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
34880 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
34890 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
348a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
348b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
348c0 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
348d0 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
348e0 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
348f0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
34900 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
34910 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
34920 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
34930 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
34940 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
34950 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
34960 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e   behavior..*/.in
34970 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
34980 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
34990 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
349a0 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61  I3REF: Read Data
349b0 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
349c0 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
349d0 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
349e0 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64   is used to read
349f0 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70   data from an op
34a00 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
34a10 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65   into a.** calle
34a20 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
34a30 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61  r. N bytes of da
34a40 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  ta are copied in
34a50 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66  to buffer Z.** f
34a60 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  rom the open BLO
34a70 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
34a80 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e  ffset iOffset.)^
34a90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  .**.** ^If offse
34aa0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
34ab0 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
34ac0 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
34ad0 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
34ae0 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
34af0 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
34b00 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66  ta is read.  ^If
34b10 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73   N or iOffset is
34b20 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
34b30 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ro, [SQLITE_ERRO
34b40 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34b50 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
34b60 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65  ad..** ^The size
34b70 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e   of the blob (an
34b80 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
34b90 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
34ba0 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
34bb0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
34bc0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
34bd0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
34be0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
34bf0 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  An attempt to re
34c00 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72  ad from an expir
34c10 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
34c20 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
34c30 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
34c40 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
34c50 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
34c60 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ss, sqlite3_blob
34c70 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  _read() returns 
34c80 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74  SQLITE_OK..** Ot
34c90 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
34ca0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
34cb0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
34cc0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
34cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
34ce0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
34cf0 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
34d00 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
34d10 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
34d20 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
34d30 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
34d40 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
34d50 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
34d60 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
34d70 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
34d80 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
34d90 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
34da0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
34db0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
34dc0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
34dd0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
34de0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
34df0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
34e00 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
34e10 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a  _blob_write()]..
34e20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
34e30 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
34e40 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
34e50 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
34e60 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
34e70 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61  PI3REF: Write Da
34e80 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
34e90 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
34ea0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
34eb0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
34ec0 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
34ed0 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
34ee0 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
34ef0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
34f00 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66  fer. ^N bytes of
34f10 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
34f20 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
34f30 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f   Z.** into the o
34f40 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
34f50 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
34f60 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  fset..**.** ^If 
34f70 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
34f80 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
34f90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77  first argument w
34fa0 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
34fb0 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68  r.** writing (th
34fc0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
34fd0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  r to [sqlite3_bl
34fe0 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a  ob_open()] was z
34ff0 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75  ero),.** this fu
35000 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
35010 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
35020 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
35030 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20  nction may only 
35040 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65  modify the conte
35050 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b  nts of the BLOB;
35060 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f   it is.** not po
35070 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61  ssible to increa
35080 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  se the size of a
35090 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73   BLOB using this
350a0 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66   API..** ^If off
350b0 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
350c0 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
350d0 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
350e0 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
350f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
35100 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
35110 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
35120 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65    ^If N is.** le
35130 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
35140 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
35150 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
35160 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
35170 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  ** The size of t
35180 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e  he BLOB (and hen
35190 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
351a0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
351b0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
351c0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
351d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
351e0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
351f0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
35200 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74  tempt to write t
35210 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  o an expired [BL
35220 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
35230 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
35240 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
35250 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74  E_ABORT].  ^Writ
35260 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74  es to the BLOB t
35270 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20  hat occurred.** 
35280 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42  before the [BLOB
35290 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64   handle] expired
352a0 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20   are not rolled 
352b0 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65  back by the.** e
352c0 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
352d0 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20   handle, though 
352e0 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20  of course those 
352f0 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a  changes might.**
35300 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77   have been overw
35310 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74  ritten by the st
35320 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70  atement that exp
35330 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61  ired the BLOB ha
35340 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74  ndle.** or by ot
35350 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  her independent 
35360 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
35370 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
35380 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
35390 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  te() returns SQL
353a0 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
353b0 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
353c0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
353d0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
353e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
353f0 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
35400 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
35410 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
35420 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
35430 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
35440 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
35450 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
35460 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
35470 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
35480 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
35490 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
354a0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
354b0 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
354c0 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
354d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
354e0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
354f0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
35500 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
35510 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
35520 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
35530 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a  lob_read()]..*/.
35540 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
35550 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
35560 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
35570 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
35580 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
35590 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
355a0 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
355b0 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20  Objects.**.** A 
355c0 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
355d0 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
355e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
355f0 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
35600 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
35610 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
35620 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
35630 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
35640 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
35650 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
35660 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
35670 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
35680 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
35690 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
356a0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
356b0 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
356c0 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
356d0 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
356e0 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
356f0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
35700 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
35710 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35720 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
35730 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35740 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
35750 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
35760 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20  ..** ^Names are 
35770 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a  case sensitive..
35780 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65  ** ^Names are ze
35790 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
357a0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
357b0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
357c0 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f  match, a NULL po
357d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
357e0 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61  d..** ^If zVfsNa
357f0 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
35800 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
35810 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
35820 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61 72  ** ^New VFSes ar
35830 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
35840 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  h sqlite3_vfs_re
35850 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61  gister()..** ^Ea
35860 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d  ch new VFS becom
35870 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  es the default V
35880 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66  FS if the makeDf
35890 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a  lt flag is set..
358a0 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46 53  ** ^The same VFS
358b0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
358c0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
358d0 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79  s without injury
358e0 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e  ..** ^To make an
358f0 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e   existing VFS in
35900 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  to the default V
35910 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20  FS, register it 
35920 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  again.** with th
35930 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
35940 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66  set.  If two dif
35950 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74  ferent VFSes wit
35960 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61  h the.** same na
35970 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65  me are registere
35980 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  d, the behavior 
35990 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49  is undefined.  I
359a0 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  f a.** VFS is re
359b0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20  gistered with a 
359c0 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c  name that is NUL
359d0 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
359e0 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ring,.** then th
359f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
35a00 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
35a10 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
35a20 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
35a30 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
35a40 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
35a50 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75 6c   ^(If the defaul
35a60 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
35a70 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
35a80 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
35a90 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
35aa0 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
35ab0 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
35ac0 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73  rbitrary.)^.*/.s
35ad0 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
35ae0 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
35af0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
35b00 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
35b10 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
35b20 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
35b30 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
35b40 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
35b50 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
35b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35b70 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a  REF: Mutexes.**.
35b80 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
35b90 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  re uses these ro
35ba0 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61  utines for threa
35bb0 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61  d.** synchroniza
35bc0 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65  tion. Though the
35bd0 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
35be0 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
35bf0 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
35c00 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
35c10 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
35c20 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
35c30 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
35c40 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
35c50 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
35c60 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
35c70 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
35c80 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20  entations.** of 
35c90 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74  these mutex rout
35ca0 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70  ines.  An approp
35cb0 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61  riate implementa
35cc0 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63  tion.** is selec
35cd0 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ted automaticall
35ce0 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  y at compile-tim
35cf0 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  e.  ^(The follow
35d00 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
35d10 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
35d20 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
35d30 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
35d40 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
35d50 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
35d60 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
35d70 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
35d80 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
35d90 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
35da0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
35db0 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NOOP.** </ul>)^.
35dc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  **.** ^The SQLIT
35dd0 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70  E_MUTEX_NOOP imp
35de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
35df0 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73   set of routines
35e00 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
35e10 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e   real locking an
35e20 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  d is appropriate
35e30 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61   for use in.** a
35e40 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
35e50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e   application.  ^
35e60 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
35e70 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f  _OS2,.** SQLITE_
35e80 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61  MUTEX_PTHREAD, a
35e90 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
35ea0 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  W32 implementati
35eb0 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f  ons.** are appro
35ec0 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f  priate for use o
35ed0 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e  n OS/2, Unix, an
35ee0 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a  d Windows..**.**
35ef0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73 20   ^(If SQLite is 
35f00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
35f10 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  e SQLITE_MUTEX_A
35f20 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73  PPDEF preprocess
35f30 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69  or.** macro defi
35f40 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c  ned (with "-DSQL
35f50 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
35f60 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75  =1"), then no mu
35f70 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
35f80 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65  ation is include
35f90 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
35fa0 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  ry. In this case
35fb0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
35fc0 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
35fd0 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69  a custom mutex i
35fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
35ff0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
36000 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
36010 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73   option of the s
36020 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
36030 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f  function.** befo
36040 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  re calling sqlit
36050 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
36060 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62  or any other pub
36070 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20  lic sqlite3_.** 
36080 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
36090 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
360a0 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a  ialize().)^.**.*
360b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
360c0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
360d0 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
360e0 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
360f0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
36100 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 69  ter to it. ^If i
36110 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a  t returns NULL.*
36120 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61  * that means tha
36130 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20  t a mutex could 
36140 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  not be allocated
36150 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69  .  ^SQLite.** wi
36160 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
36170 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
36180 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 20  n error.  ^(The 
36190 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
361a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
361b0 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
361c0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
361d0 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
361e0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
361f0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
36200 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36210 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
36220 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36230 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
36240 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
36250 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
36260 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
36270 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36280 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
36290 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
362a0 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
362b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
362c0 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
362d0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
362e0 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
362f0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
36300 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
36310 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45  nts (SQLITE_MUTE
36320 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
36330 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36340 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c 69  E).** cause sqli
36350 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36360 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61  ) to create.** a
36370 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 68   new mutex.  ^Th
36380 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72  e new mutex is r
36390 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51  ecursive when SQ
363a0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
363b0 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20  SIVE.** is used 
363c0 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  but not necessar
363d0 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49  ily so when SQLI
363e0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73  TE_MUTEX_FAST is
363f0 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75   used..** The mu
36400 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
36410 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
36420 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
36430 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
36440 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
36450 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c  ECURSIVE and SQL
36460 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
36470 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
36480 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69   want to.  ^SQLi
36490 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71  te will only req
364a0 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65  uest a recursive
364b0 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73   mutex in.** cas
364c0 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c  es where it real
364d0 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e  ly needs one.  ^
364e0 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d  If a faster non-
364f0 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a  recursive mutex.
36500 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
36510 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  n is available o
36520 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66  n the host platf
36530 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73  orm, the mutex s
36540 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68  ubsystem.** migh
36550 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20  t return such a 
36560 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73  mutex in respons
36570 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  e to SQLITE_MUTE
36580 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54  X_FAST..**.** ^T
36590 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
365a0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
365b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
365c0 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20 6f  oc() (anything o
365d0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c  ther.** than SQL
365e0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
365f0 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36600 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68 20  RECURSIVE) each 
36610 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
36620 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
36630 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
36640 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63 20  x.  ^Six static 
36650 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
36660 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
36670 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
36680 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
36690 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
366a0 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
366b0 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
366c0 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
366d0 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
366e0 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
366f0 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
36700 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
36710 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
36720 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
36730 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
36740 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
36750 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
36760 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
36770 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36780 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  URSIVE..**.** ^N
36790 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20  ote that if one 
367a0 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  of the dynamic m
367b0 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20  utex parameters 
367c0 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
367d0 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f  ST.** or SQLITE_
367e0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
367f0 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71   is used then sq
36800 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
36810 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  c().** returns a
36820 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78   different mutex
36830 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20   on every call. 
36840 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73 74   ^But for the st
36850 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79  atic.** mutex ty
36860 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
36870 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
36880 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
36890 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
368a0 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a  me type number..
368b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
368c0 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20  e3_mutex_free() 
368d0 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61  routine dealloca
368e0 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79  tes a previously
368f0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79  .** allocated dy
36900 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e 53  namic mutex.  ^S
36910 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
36920 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
36930 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
36940 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
36950 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64 79  locates.  The dy
36960 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
36970 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20  st not be in.** 
36980 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72  use when they ar
36990 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20  e deallocated.  
369a0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
369b0 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
369c0 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
369d0 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
369e0 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69  behavior.  ^SQLi
369f0 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
36a00 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
36a10 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54   mutex..**.** ^T
36a20 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
36a30 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c  _enter() and sql
36a40 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
36a50 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
36a60 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20  t.** to enter a 
36a70 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74  mutex.  ^If anot
36a80 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c  her thread is al
36a90 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65  ready within the
36aa0 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74   mutex,.** sqlit
36ab0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36ac0 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20   will block and 
36ad0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36ae0 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  y() will return.
36af0 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ** SQLITE_BUSY. 
36b00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36b10 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
36b20 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
36b30 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
36b40 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
36b50 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72 65  .  ^(Mutexes cre
36b60 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ated using.** SQ
36b70 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
36b80 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65  SIVE can be ente
36b90 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
36ba0 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
36bb0 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63  hread..** In suc
36bc0 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
36bd0 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
36be0 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
36bf0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
36c00 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
36c10 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
36c20 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73 61  .)^  ^(If the sa
36c30 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20  me thread tries 
36c40 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68  to enter any oth
36c50 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75  er.** kind of mu
36c60 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  tex more than on
36c70 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ce, the behavior
36c80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36c90 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
36ca0 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73  ver exhibit.** s
36cb0 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20  uch behavior in 
36cc0 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d  its own use of m
36cd0 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  utexes.)^.**.** 
36ce0 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28  ^(Some systems (
36cf0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e  for example, Win
36d00 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20  dows 95) do not 
36d10 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72  support the oper
36d20 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ation.** impleme
36d30 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  nted by sqlite3_
36d40 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e  mutex_try().  On
36d50 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20   those systems, 
36d60 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36d70 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  y().** will alwa
36d80 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ys return SQLITE
36d90 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69  _BUSY.  The SQLi
36da0 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65  te core only eve
36db0 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65  r uses.** sqlite
36dc0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73  3_mutex_try() as
36dd0 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
36de0 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65   so this is acce
36df0 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ptable behavior.
36e00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
36e10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
36e20 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  e() routine exit
36e30 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
36e40 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
36e50 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
36e60 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20 5e  same thread.   ^
36e70 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a  (The behavior.**
36e80 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
36e90 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
36ea0 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
36eb0 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
36ec0 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
36ed0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
36ee0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
36ef0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
36f00 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a  r do either.)^.*
36f10 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
36f20 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
36f30 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20  _mutex_enter(), 
36f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36f50 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  y(), or.** sqlit
36f60 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
36f70 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
36f80 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72  er, then all thr
36f90 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62  ee routines.** b
36fa0 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e  ehave as no-ops.
36fb0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
36fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36fd0 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  held()] and [sql
36fe0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
36ff0 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ld()]..*/.sqlite
37000 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33  3_mutex *sqlite3
37010 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74  _mutex_alloc(int
37020 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37030 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74  mutex_free(sqlit
37040 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64  e3_mutex*);.void
37050 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37060 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74  nter(sqlite3_mut
37070 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
37080 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69  3_mutex_try(sqli
37090 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
370a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
370b0 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75  leave(sqlite3_mu
370c0 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
370d0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65  PI3REF: Mutex Me
370e0 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
370f0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
37100 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
37110 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77   defines the low
37120 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a  -level routines.
37130 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63  ** used to alloc
37140 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65  ate and use mute
37150 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c  xes..**.** Usual
37160 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ly, the default 
37170 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
37180 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62  tions provided b
37190 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20  y SQLite are.** 
371a0 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65  sufficient, howe
371b0 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73  ver the user has
371c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73   the option of s
371d0 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75  ubstituting a cu
371e0 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  stom.** implemen
371f0 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69  tation for speci
37200 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e  alized deploymen
37210 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f  ts or systems fo
37220 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a  r which SQLite.*
37230 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  * does not provi
37240 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  de a suitable im
37250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e  plementation. In
37260 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
37270 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20  user.** creates 
37280 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  and populates an
37290 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
372a0 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70  s structure to p
372b0 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ass.** to sqlite
372c0 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67  3_config() along
372d0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
372e0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
372f0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74  option..** Addit
37300 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74  ionally, an inst
37310 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
37320 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  ucture can be us
37330 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70  ed as an.** outp
37340 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e  ut variable when
37350 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79   querying the sy
37360 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72  stem for the cur
37370 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  rent mutex.** im
37380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73  plementation, us
37390 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
373a0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
373b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   option..**.** ^
373c0 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  The xMutexInit m
373d0 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79  ethod defined by
373e0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
373f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a  is invoked as.**
37400 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20   part of system 
37410 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62  initialization b
37420 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
37430 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  itialize() funct
37440 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ion..** ^The xMu
37450 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
37460 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51 4c 69  is calle by SQLi
37470 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  te exactly once 
37480 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65  for each.** effe
37490 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73  ctive call to [s
374a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
374b0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
374c0 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f   xMutexEnd metho
374d0 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
374e0 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
374f0 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
37500 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74  t of system shut
37510 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69  down by the sqli
37520 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66  te3_shutdown() f
37530 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20  unction. The.** 
37540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37550 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73  f this method is
37560 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c   expected to rel
37570 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e  ease all outstan
37580 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65  ding.** resource
37590 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  s obtained by th
375a0 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20  e mutex methods 
375b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
375c0 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68  especially.** th
375d0 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ose obtained by 
375e0 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  the xMutexInit m
375f0 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75  ethod.  ^The xMu
37600 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65  texEnd().** inte
37610 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b 65 64  rface is invoked
37620 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f   exactly once fo
37630 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  r each call to [
37640 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
37650 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ()]..**.** ^(The
37660 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e   remaining seven
37670 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
37680 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
37690 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c  re (xMutexAlloc,
376a0 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20  .** xMutexFree, 
376b0 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75  xMutexEnter, xMu
376c0 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65  texTry, xMutexLe
376d0 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20  ave, xMutexHeld 
376e0 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74  and.** xMutexNot
376f0 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20  held) implement 
37700 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
37710 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63  terfaces (respec
37720 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c  tively):.**.** <
37730 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  ul>.**   <li>  [
37740 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
37750 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  loc()] </li>.** 
37760 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37770 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c  _mutex_free()] <
37780 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37790 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
377a0 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  nter()] </li>.**
377b0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
377c0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c  3_mutex_try()] <
377d0 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
377e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
377f0 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  eave()] </li>.**
37800 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37810 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
37820 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
37830 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37840 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  notheld()] </li>
37850 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
37860 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65  * The only diffe
37870 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68  rence is that th
37880 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  e public sqlite3
37890 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65  _XXX functions e
378a0 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f  numerated.** abo
378b0 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ve silently igno
378c0 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f  re any invocatio
378d0 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e  ns that pass a N
378e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
378f0 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69  ead.** of a vali
37900 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20  d mutex handle. 
37910 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
37920 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f  ons of the metho
37930 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  ds defined.** by
37940 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
37950 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64  are not required
37960 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20   to handle this 
37970 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74  case, the result
37980 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20  s.** of passing 
37990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
379a0 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69  nstead of a vali
379b0 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61  d mutex handle a
379c0 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20  re undefined.** 
379d0 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65  (i.e. it is acce
379e0 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64  ptable to provid
379f0 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e an implementat
37a00 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c  ion that segfaul
37a10 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70  ts if.** it is p
37a20 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69  assed a NULL poi
37a30 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nter)..**.** The
37a40 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 65   xMutexInit() me
37a50 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68 72  thod must be thr
37a60 65 61 64 73 61 66 65 2e 20 20 5e 49 74 20 6d 75  eadsafe.  ^It mu
37a70 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20 74  st be harmless t
37a80 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74  o.** invoke xMut
37a90 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c 65  exInit() mutiple
37aa0 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68   times within th
37ab0 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61  e same process a
37ac0 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e  nd without.** in
37ad0 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20  tervening calls 
37ae0 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20  to xMutexEnd(). 
37af0 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   Second and subs
37b00 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37b10 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  ** xMutexInit() 
37b20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a  must be no-ops..
37b30 2a 2a 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69  **.** ^xMutexIni
37b40 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65  t() must not use
37b50 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61   SQLite memory a
37b60 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69  llocation ([sqli
37b70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
37b80 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61   and its associa
37b90 74 65 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c  tes).  ^Similarl
37ba0 79 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  y, xMutexAlloc()
37bb0 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
37bc0 4c 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Lite memory.** a
37bd0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20  llocation for a 
37be0 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 5e  static mutex.  ^
37bf0 48 6f 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c  However xMutexAl
37c00 6c 6f 63 28 29 20 6d 61 79 20 75 73 65 20 53 51  loc() may use SQ
37c10 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  Lite.** memory a
37c20 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20  llocation for a 
37c30 66 61 73 74 20 6f 72 20 72 65 63 75 72 73 69 76  fast or recursiv
37c40 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e  e mutex..**.** ^
37c50 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
37c60 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45 6e 64  ke the xMutexEnd
37c70 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b  () method when [
37c80 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
37c90 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  ()] is.** called
37ca0 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 68  , but only if th
37cb0 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  e prior call to 
37cc0 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74 75 72  xMutexInit retur
37cd0 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  ned SQLITE_OK..*
37ce0 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69 74 20  * If xMutexInit 
37cf0 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 79  fails in any way
37d00 2c 20 69 74 20 69 73 20 65 78 70 65 63 74 65 64  , it is expected
37d10 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74   to clean up aft
37d20 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69  er itself.** pri
37d30 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e  or to returning.
37d40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
37d50 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
37d60 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
37d70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a  _mutex_methods;.
37d80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
37d90 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  utex_methods {. 
37da0 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69   int (*xMutexIni
37db0 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20  t)(void);.  int 
37dc0 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69  (*xMutexEnd)(voi
37dd0 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75  d);.  sqlite3_mu
37de0 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c  tex *(*xMutexAll
37df0 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64  oc)(int);.  void
37e00 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73   (*xMutexFree)(s
37e10 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37e20 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
37e30 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d  Enter)(sqlite3_m
37e40 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28  utex *);.  int (
37e50 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69  *xMutexTry)(sqli
37e60 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37e70 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65 61  void (*xMutexLea
37e80 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ve)(sqlite3_mute
37e90 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37ea0 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74 65  utexHeld)(sqlite
37eb0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e  3_mutex *);.  in
37ec0 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c  t (*xMutexNothel
37ed0 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d)(sqlite3_mutex
37ee0 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *);.};../*.** C
37ef0 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 56  API3REF: Mutex V
37f00 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75 74  erification Rout
37f10 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ines.**.** The s
37f20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
37f30 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
37f40 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
37f50 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
37f60 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
37f70 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
37f80 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
37f90 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a  he SQLite core.*
37fa0 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65  * never uses the
37fb0 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65  se routines exce
37fc0 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73  pt inside an ass
37fd0 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63  ert() and applic
37fe0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64  ations.** are ad
37ff0 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20  vised to follow 
38000 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20  the lead of the 
38010 63 6f 72 65 2e 20 20 5e 54 68 65 20 53 51 4c 69  core.  ^The SQLi
38020 74 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20  te core only.** 
38030 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65  provides impleme
38040 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  ntations for the
38050 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e  se routines when
38060 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a   it is compiled.
38070 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ** with the SQLI
38080 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20  TE_DEBUG flag.  
38090 5e 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20  ^External mutex 
380a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
380b0 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
380c0 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
380d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
380e0 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
380f0 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
38100 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
38110 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
38120 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
38130 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
38140 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78  rue if the mutex
38150 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65   in their argume
38160 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72  nt.** is held or
38170 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65   not held, respe
38180 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20  ctively, by the 
38190 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a  calling thread..
381a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65  **.** ^The imple
381b0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
381c0 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
381d0 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
381e0 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
381f0 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
38200 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69  y work. If the i
38210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
38220 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
38230 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
38240 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
38250 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
38260 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
38270 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61   stubs that alwa
38280 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75  ys.** return tru
38290 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
382a0 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
382b0 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61  ous assertion fa
382c0 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ilures..**.** ^I
382d0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
382e0 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
382f0 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c  held() is a NULL
38300 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
38310 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f   the routine sho
38320 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 20  uld return 1.   
38330 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e 74  This seems count
38340 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69 6e  er-intuitive sin
38350 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68  ce.** clearly th
38360 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20 62  e mutex cannot b
38370 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f 65  e held if it doe
38380 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42 75  s not exist.  Bu
38390 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65 61  t the.** the rea
383a0 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64 6f  son the mutex do
383b0 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73 20  es not exist is 
383c0 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  because the buil
383d0 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e  d is not.** usin
383e0 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64 20  g mutexes.  And 
383f0 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74  we do not want t
38400 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e 74  he assert() cont
38410 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61  aining the.** ca
38420 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ll to sqlite3_mu
38430 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66 61  tex_held() to fa
38440 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72  il, so a non-zer
38450 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74  o return is.** t
38460 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 74  he appropriate t
38470 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 5e 54 68  hing to do.  ^Th
38480 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
38490 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74  notheld().** int
384a0 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61 6c  erface should al
384b0 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65 6e  so return 1 when
384c0 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f   given a NULL po
384d0 69 6e 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65  inter..*/.#ifnde
384e0 66 20 4e 44 45 42 55 47 0a 69 6e 74 20 73 71 6c  f NDEBUG.int sql
384f0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
38500 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
38510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
38520 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74  ex_notheld(sqlit
38530 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 23 65 6e 64  e3_mutex*);.#end
38540 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
38550 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 0a  EF: Mutex Types.
38560 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
38570 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
38580 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b 65  ] interface take
38590 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
385a0 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73 20  ent.** which is 
385b0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
385c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  eger constants..
385d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f 66  **.** The set of
385e0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
385f0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 20  may change from 
38600 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65 61  one SQLite relea
38610 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  se to the.** nex
38620 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
38630 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20 74   that override t
38640 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74 65  he built-in mute
38650 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65 0a  x logic must be.
38660 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20 61  ** prepared to a
38670 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69 74  ccommodate addit
38680 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74  ional static mut
38690 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  exes..*/.#define
386a0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
386b0 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20 30  ST             0
386c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
386d0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
386e0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
386f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38700 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20 32  ATIC_MASTER    2
38710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38720 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
38730 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71 6c         3  /* sql
38740 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f  ite3_malloc() */
38750 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38760 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
38770 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f 54  2      4  /* NOT
38780 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e 65   USED */.#define
38790 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
387a0 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20 34  ATIC_OPEN      4
387b0 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72 65    /* sqlite3Btre
387c0 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66 69  eOpen() */.#defi
387d0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
387e0 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20 20  STATIC_PRNG     
387f0 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 72   5  /* sqlite3_r
38800 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66 69  andom() */.#defi
38810 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
38820 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20 20  STATIC_LRU      
38830 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20   6  /* lru page 
38840 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  list */.#define 
38850 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
38860 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37 20  TIC_LRU2      7 
38870 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73   /* lru page lis
38880 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t */../*.** CAPI
38890 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20 74  3REF: Retrieve t
388a0 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20 64  he mutex for a d
388b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
388c0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  on.**.** ^This i
388d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
388e0 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20 5b   a pointer the [
388f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex