/ Hex Artifact Content
Login

Artifact 846a91e163497b596b5bbebd26477eaf234eb1c0:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
41d0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
41e0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
41f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4200: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4210: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4220: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4230: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4250: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4260: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4280: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4290: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42a0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
42c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
42d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
42e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
42f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4310: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4320: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4330: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4360: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4370: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4380: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4390: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
43c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
43f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4400: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4410: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4420: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4430: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4440: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4460: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4470: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4480: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4490: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
44c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
44f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4500: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4510: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4520: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4530: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4540: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4550: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4560: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4570: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4580: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4590: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
45c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
45d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
45e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
45f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4620: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4630: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4640: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4650: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4660: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4670: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4680: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4690: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46a0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46b0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
46c0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
46d0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
46e0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
46f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4700: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4710: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4720: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4730: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4740: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4750: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4760: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4770: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4780: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4790: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47a0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47b0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
47c0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
47d0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
47e0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
47f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4800: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4810: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4820: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4830: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4840: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4850: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4860: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4870: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4880: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4890: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48a0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48b0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
48c0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
48d0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
48e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
48f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4900: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4910: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4930: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4940: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4950: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4960: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4970: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4980: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4990: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49a0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49b0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
49c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
49d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49e0: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
49f0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a00: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a10: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a20: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a30: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a40: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a50: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4a60: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4a70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4a80: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4a90: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4aa0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4ab0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4ac0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4af0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b00: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4ce0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d20: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4d60: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4da0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4de0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e20: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4e60: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ea0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f20: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
4fe0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
4ff0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5000: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5010: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5020: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5030: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5040: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5050: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5060: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5070: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5080: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
5090: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
50a0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
50b0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
50c0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
50d0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
50e0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
50f0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5100: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5110: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5120: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5130: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5140: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5150: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5160: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5170: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5190: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
51a0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
51b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
51c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
51d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
51e0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
51f0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5200: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5210: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5220: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5230: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5240: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5250: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5260: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5280: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5290: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
52a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
52c0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
52d0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
52e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5300: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5310: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5320: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5340: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5350: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5360: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5370: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5380: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5390: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
53a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
53c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
53d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
53e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5400: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5410: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5420: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5440: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5450: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5460: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5470: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5480: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5490: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
54a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
54c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
54d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
54e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5500: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5510: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5520: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5530: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5540: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5550: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5560: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5570: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5580: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5590: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
55a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
55b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
55c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
55d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
55e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
55f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5600: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5610: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5620: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5650: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
5660: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
5670: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5690: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
56a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
56b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
56c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
56d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
56e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
56f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5700: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5710: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
5720: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
5730: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
5740: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5750: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5760: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5770: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5780: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5790: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
57a0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
57b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
57c0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
57d0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
57e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
57f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5800: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5810: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
5820: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5840: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5850: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5860: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5870: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5880: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5890: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
58a0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
58b0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
58c0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
58f0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5900: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5910: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
5920: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
5930: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
5940: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5960: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5970: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5980: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5990: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
59a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
59b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
59c0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
59d0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
59e0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
59f0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a20: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5a30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5a40: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5a50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5a60: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5a70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5aa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ab0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5ac0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ad0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5ae0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5af0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b00: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b20: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b50: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5b60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b70: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5b80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bc0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5be0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5bf0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c10: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5c20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c30: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5c40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5c50: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5c60: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c80: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5c90: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5ca0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5cb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5cc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5cd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5ce0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5cf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5d20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5d30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5d40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5d50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5d60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5d90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5da0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5db0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5dc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5dd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5df0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5e20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5e30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5e40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5e50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5e60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5e70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5e80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5e90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5ea0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5eb0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5ec0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ed0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5ee0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5ef0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5f20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5f30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5f40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5f50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5f60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5f70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5f80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5f90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5fa0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5fb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5fc0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5fd0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5fe0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ff0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6000: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6010: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6020: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6030: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6040: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6050: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6060: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6070: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6080: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
60b0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
60c0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
60d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
60e0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
60f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6100: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6110: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6120: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6130: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6140: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6150: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6160: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6170: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6180: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6190: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
61a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
61b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
61c0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
61d0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
61e0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
61f0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6200: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6210: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
6220: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
6230: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
6240: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
6250: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
6260: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
6270: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6280: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6290: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
62a0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
62b0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
62c0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
62d0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
62e0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
62f0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6300: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6310: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
6320: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
6330: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
6340: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6350: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6360: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6370: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
63b0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
63c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
63d0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
63e0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
63f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6400: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6410: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
6420: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
6430: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
6440: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
6450: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
6460: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
6470: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6480: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6490: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
64a0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
64b0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
64c0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
64d0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
64e0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
64f0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6510: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6520: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6530: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6540: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6550: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6560: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6570: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6580: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
65a0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
65b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65c0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
65d0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
65e0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
65f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6600: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6610: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6620: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
6630: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6640: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6650: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
6660: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
6670: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6680: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6690: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
66a0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
66b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
66c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
66d0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
66e0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
66f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6710: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6720: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6730: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6740: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6750: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6760: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6780: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6790: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
67a0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
67b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
67c0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
67d0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
67e0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
67f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6800: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6810: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
6820: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
6830: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6840: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6850: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6860: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6870: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6880: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6890: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
68a0: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
68b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
68c0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
68d0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
68e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
68f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6900: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6910: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6920: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6930: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6940: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6950: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6960: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6970: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6980: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6990: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
69a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
69b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
69c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
69d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
69e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
69f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a00: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a10: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6a20: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6a30: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6a40: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6a50: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6a60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6a70: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6a80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6a90: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6ab0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6ad0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6ae0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6af0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b00: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b10: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6b20: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6b30: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6b40: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6b50: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6b60: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6b70: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6b80: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6b90: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ba0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6bb0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6bc0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6bd0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6be0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6bf0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c00: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c10: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6c20: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6c30: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6c40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6c50: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6c60: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6c70: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6c80: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6c90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6ca0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6cb0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6cc0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6ce0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6cf0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d00: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d10: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6d20: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6d30: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6d40: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6d50: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6d60: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6d70: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6d80: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6d90: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6da0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6db0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6dc0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6dd0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6de0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6df0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6e20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6e30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6e40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6e50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6e60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6e70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6e80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6e90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6ea0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6eb0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6ec0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6ed0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6ee0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6ef0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6f20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6f30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6f40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6f50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6f60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6f70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6f80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6f90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6fa0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
6fb0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6fc0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
6fd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
6fe0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
6ff0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7000: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7010: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7020: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7030: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7040: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7050: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7060: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7070: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7080: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7090: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
70a0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
70b0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
70c0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
70d0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
70e0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
70f0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7100: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7110: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7120: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7130: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7140: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7150: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7160: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7180: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
71a0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
71b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71c0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
71d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71e0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7220: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7250: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7260: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7280: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
72a0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
72b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72c0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
72d0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
72e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
72f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7300: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7310: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7320: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7330: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7340: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7350: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7360: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7370: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7380: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7390: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
73a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
73b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
73c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
73d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
73e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7400: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7410: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7420: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7430: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7440: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7450: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7460: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7470: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7480: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7490: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
74a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
74b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
74c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
74d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
74e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
74f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7500: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7510: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7520: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7530: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7540: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7550: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7560: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7570: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7580: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7590: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
75a0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
75b0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
75c0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
75d0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
75e0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
75f0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7600: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7610: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7620: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7630: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7660: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7680: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7690: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
76a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
76b0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
76c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
76d0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
76e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
76f0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7700: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7710: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7720: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7730: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7740: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7750: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7760: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7770: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7780: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7790: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
77a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
77b0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
77c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
77d0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
77e0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
77f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7800: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7830: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7850: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7860: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7870: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7880: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7890: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
78a0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
78b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78c0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
78d0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
78e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7900: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7910: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7920: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7930: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7940: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7950: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7960: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7970: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7980: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7990: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
79a0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
79b0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
79c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
79d0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
79e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79f0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a00: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a10: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7a20: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7a30: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7a40: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7a50: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7a60: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7a80: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7a90: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7aa0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7ab0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7ac0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7ad0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7ae0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7af0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b00: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7b20: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7b30: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7b50: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7b60: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7b70: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7b80: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7b90: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7ba0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7bb0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7bc0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7bd0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7be0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c00: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c10: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c30: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7c40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7c50: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7c60: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7c70: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7c80: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7c90: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7ca0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7cb0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7cc0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7cd0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7ce0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7cf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d00: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d10: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7d20: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7d30: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7d40: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7d50: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7d60: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7d70: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7d90: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7da0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7db0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7dc0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7dd0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7de0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7df0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e00: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e10: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7e20: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7e30: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7e40: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7e50: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7e60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7e70: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7e80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7e90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7ea0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7eb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7ec0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7ed0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7ee0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7ef0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f00: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f10: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7f20: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7f30: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7f40: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7f50: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7f60: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7f70: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
7f80: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
7f90: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
7fa0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
7fb0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
7fc0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
7fd0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
7fe0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
7ff0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8000: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8010: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8020: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8030: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8040: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8050: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
8060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8070: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8090: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
80a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
80b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
80c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
80d0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
80e0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
80f0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8100: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8110: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8120: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8130: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8140: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
8150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8160: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8170: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8180: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8190: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
81a0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
81b0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
81c0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
81d0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
81e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
81f0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8200: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8210: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8220: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8230: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8240: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8250: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8260: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8270: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8280: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8290: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
82a0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
82b0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
82c0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
82d0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
82e0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
82f0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8310: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8320: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8330: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8340: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8350: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8360: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8370: 65 63 69 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  ecilized VFSes.*
8380: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8390: 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69  e it.  .*/.#defi
83a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
83b0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
83c0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
83d0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
83e0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
83f0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
8400: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8410: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
8420: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
8430: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
8440: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8450: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
8460: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
8470: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8480: 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69  ZE       6.#defi
8490: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
84a0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
84b0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
84c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
84d0: 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  TTED     8.../*.
84e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
84f0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
8500: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
8510: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
8520: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
8530: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
8540: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
8550: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
8560: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
8570: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
8580: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
8590: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
85a0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
85b0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
85c0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
85d0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
85e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
85f0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
8600: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
8610: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
8620: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
8630: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
8640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
8650: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
8660: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8670: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
8680: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
8690: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
86a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
86b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
86c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
86d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
86e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
86f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8700: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8710: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8720: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8730: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8740: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8750: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8760: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8770: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8780: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8790: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
87a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
87b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
87c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
87d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
87e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
87f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8800: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8810: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8820: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8830: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8840: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8850: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8860: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8870: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8880: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8890: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
88a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
88b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
88c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
88d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
88e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
88f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8900: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8910: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8920: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8930: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8940: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8950: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8960: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8970: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8980: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8990: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
89a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
89b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
89c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
89d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
89e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
89f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8a00: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8a10: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8a20: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8a30: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8a40: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8a50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8a60: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8a70: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8a80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8a90: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
8aa0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8ab0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
8ac0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
8ad0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
8ae0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
8af0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8b00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8b10: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8b20: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8b30: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8b40: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8b50: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8b60: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8b70: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8b80: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8b90: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8ba0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
8bb0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
8bc0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
8bd0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
8be0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
8bf0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8c00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8c10: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8c20: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8c30: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8c40: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8c50: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8c60: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8c70: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8c80: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8c90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8ca0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8cb0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8cc0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8cd0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8ce0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
8cf0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8d00: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8d10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8d20: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8d30: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8d40: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8d50: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8d60: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8d70: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8d80: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8d90: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
8da0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
8db0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
8dc0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8dd0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
8de0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
8df0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8e00: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8e10: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8e20: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8e30: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8e40: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8e50: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8e60: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8e70: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8e80: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8e90: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
8ea0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
8eb0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
8ec0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
8ed0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8ee0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8ef0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8f00: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8f10: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8f20: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8f30: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8f40: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8f50: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8f60: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8f70: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8f90: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
8fa0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
8fb0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8fc0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
8fd0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8fe0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
8ff0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
9000: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
9010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9020: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
9030: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
9040: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
9050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
9060: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
9070: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
9080: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
9090: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
90a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
90b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
90c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
90d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
90e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
90f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
9100: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9110: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
9120: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
9130: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
9140: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
9150: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
9160: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
9170: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
9180: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
9190: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
91a0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
91b0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
91c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
91d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
91e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
91f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9200: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9210: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
9220: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
9230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
9240: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
9250: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9260: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
9270: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9280: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
9290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
92a0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
92b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
92c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
92d0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
92e0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
92f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9300: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
9310: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
9320: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
9330: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
9340: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
9350: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
9360: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
9370: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
9380: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
9390: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
93a0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
93b0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
93c0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
93d0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
93e0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
93f0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
9400: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
9410: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
9420: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
9430: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
9440: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
9450: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
9460: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
9470: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9480: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
9490: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
94a0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
94b0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
94c0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
94d0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
94e0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
94f0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
9500: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
9510: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
9520: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
9530: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
9540: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
9550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
9570: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
9580: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
9590: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
95a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
95b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
95c0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
95d0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
95e0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
95f0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
9600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9610: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
9620: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
9630: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
9640: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
9650: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
9660: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
9670: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
9680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9690: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
96a0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
96b0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
96c0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
96d0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
96e0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
96f0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9700: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9710: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9720: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9730: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9740: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9750: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9760: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9770: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9780: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9790: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
97a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
97b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
97c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
97d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
97e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
97f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9800: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9810: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9820: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9830: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9840: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9850: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9860: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9870: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9880: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9890: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
98a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
98b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
98c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
98d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
98e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
98f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9900: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9910: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9920: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9930: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9940: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9950: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9960: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9980: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9990: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
99a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
99b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
99c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
99d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
99e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
99f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9a00: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9a10: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9a20: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9a30: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9a40: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9a50: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9a60: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9a70: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9a80: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9a90: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
9aa0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
9ab0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
9ac0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
9ad0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
9ae0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
9af0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9b00: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b10: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9b20: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9b30: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9b40: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9b50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9b60: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9b70: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9b80: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9b90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
9ba0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
9bb0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
9bc0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
9bd0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
9be0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
9bf0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9c00: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9c10: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9c20: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9c30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9c40: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9c50: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9c60: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9c70: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9c80: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9c90: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
9ca0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
9cb0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
9cc0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
9cd0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
9ce0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
9cf0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9d00: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9d10: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9d20: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9d30: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9d40: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9d50: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9d60: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9d70: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9d80: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9d90: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
9da0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
9db0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
9dc0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
9dd0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
9de0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
9df0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9e00: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9e10: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9e20: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9e30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9e40: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9e50: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9e60: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9e70: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9e80: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9e90: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
9ea0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
9eb0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
9ec0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
9ed0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
9ee0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
9ef0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9f00: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9f10: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9f20: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9f30: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9f40: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9f50: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9f60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9f70: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9f80: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9f90: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
9fa0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
9fb0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
9fc0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9fd0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
9fe0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
9ff0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
a000: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
a010: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
a020: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
a030: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
a040: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
a050: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
a060: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
a070: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
a080: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
a090: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
a0a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
a0b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
a0c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
a0d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
a0e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
a0f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
a100: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
a110: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
a120: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
a130: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
a140: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
a150: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
a160: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
a170: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
a180: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
a190: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
a1a0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
a1b0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
a1c0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
a1d0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
a1e0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
a1f0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
a200: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
a210: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
a220: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
a230: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
a240: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
a250: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
a260: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
a270: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
a280: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
a290: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
a2a0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
a2b0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
a2c0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
a2d0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
a2e0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
a2f0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
a300: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
a310: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
a320: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
a330: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
a340: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
a350: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
a360: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
a370: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
a380: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
a390: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
a3a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
a3b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
a3c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
a3d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
a3e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
a3f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
a400: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
a410: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
a420: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
a430: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
a440: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
a450: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
a460: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
a470: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
a480: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
a490: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a4a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
a4b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
a4c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
a4d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
a4e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
a4f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
a500: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
a510: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
a520: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
a530: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
a540: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
a550: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
a560: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
a570: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
a580: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
a590: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
a5a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
a5b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
a5c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
a5d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
a5e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
a5f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
a600: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
a610: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
a620: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
a630: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
a640: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
a650: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
a660: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
a670: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
a680: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
a690: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a6a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a6b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
a6c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
a6d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
a6e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
a6f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
a700: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a710: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a720: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
a730: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
a740: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a750: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a760: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
a770: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
a780: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
a790: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a7a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
a7b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
a7c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
a7d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
a7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
a7f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
a800: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
a810: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a820: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
a830: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
a840: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
a850: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
a860: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
a870: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
a880: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
a890: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a8a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
a8b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
a8c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
a8d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
a8e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
a8f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
a900: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
a910: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
a920: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
a930: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
a940: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
a950: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
a960: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
a970: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
a980: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
a990: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
a9a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
a9b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
a9c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
a9d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
a9e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
a9f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
aa00: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
aa10: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
aa20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
aa30: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
aa40: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
aa50: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
aa60: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
aa70: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
aa80: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
aa90: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
aaa0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
aab0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
aac0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
aad0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
aae0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
aaf0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ab00: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ab10: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ab20: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ab30: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ab40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ab50: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ab60: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ab70: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ab80: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ab90: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
aba0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
abb0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
abc0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
abd0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
abe0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
abf0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
ac00: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
ac10: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
ac20: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
ac30: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
ac40: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
ac50: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
ac60: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
ac70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
ac80: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
ac90: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
aca0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
acb0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
acc0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
acd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ace0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
acf0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ad00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ad10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ad20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ad30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ad40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ad50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ad60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ad70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ad80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ad90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ada0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
adb0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
adc0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
add0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
ade0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
adf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ae00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ae10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
ae20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ae30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
ae40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
ae50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
ae60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
ae70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
ae80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
ae90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
aea0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
aeb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
aec0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
aed0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
aee0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
aef0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
af00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
af10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
af20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
af30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
af40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
af50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
af60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
af70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
af80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
af90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
afa0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
afb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
afc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
afd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
afe0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
aff0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
b000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b010: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
b020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b030: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b040: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
b050: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
b060: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
b070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b080: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
b090: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
b0a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b0b0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
b0c0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
b0d0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
b0e0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
b0f0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
b100: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
b110: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
b120: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
b130: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
b140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
b150: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
b160: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
b170: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
b180: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
b190: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
b1a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
b1b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
b1c0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
b1d0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b1e0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b1f0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
b200: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
b210: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b220: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b230: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
b240: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
b250: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
b260: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
b280: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
b290: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
b2a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
b2b0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
b2c0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
b2d0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
b2e0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
b2f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
b300: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
b310: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
b320: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
b330: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
b340: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
b350: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
b360: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
b370: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
b380: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
b390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
b3a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
b3b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
b3c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
b3d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b3e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
b3f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
b400: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
b410: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
b420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
b430: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
b440: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
b450: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
b460: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
b470: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
b480: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
b490: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
b4a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
b4b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
b4c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
b4d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
b4e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
b4f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
b500: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
b510: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
b520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b530: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
b540: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
b550: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
b560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
b570: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
b580: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b590: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
b5a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
b5b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
b5c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
b5d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
b5e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
b5f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
b600: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
b610: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
b620: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
b630: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
b640: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
b650: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
b660: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
b670: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
b680: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
b690: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
b6a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
b6b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
b6c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
b6d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
b6e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
b6f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
b700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b710: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
b720: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
b730: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
b740: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
b750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b760: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
b770: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
b780: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
b790: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
b7a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
b7b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b7c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
b7d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
b7e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b7f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
b800: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
b810: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
b820: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
b830: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
b840: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
b850: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
b860: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
b870: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
b880: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b890: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
b8a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
b8b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
b8c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
b8d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
b8e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
b8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
b900: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
b910: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
b920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b930: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
b940: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
b950: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
b960: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b970: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
b980: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
b990: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
b9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
b9c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
b9d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b9e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
b9f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ba00: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
ba10: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
ba20: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
ba30: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
ba40: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
ba50: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
ba60: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
ba70: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
ba80: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
ba90: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
baa0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
bab0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
bac0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
bad0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
bae0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
baf0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
bb00: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
bb10: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
bb20: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
bb30: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
bb40: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
bb50: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
bb60: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
bb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
bb80: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
bb90: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
bba0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
bbb0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
bbc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bbd0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
bbe0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
bbf0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
bc00: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
bc10: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
bc20: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
bc30: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
bc40: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
bc50: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
bc60: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
bc70: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
bc80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bc90: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
bca0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
bcb0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
bcc0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
bcd0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
bce0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
bcf0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
bd00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
bd10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bd20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
bd30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
bd40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
bd50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
bd60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
bd70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
bd80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
bd90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
bda0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
bdb0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
bdc0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
bdd0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
bde0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
bdf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
be00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
be10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
be20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
be30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
be40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
be50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
be60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
be70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
be80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
be90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
bea0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
beb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
bec0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
bed0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
bee0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
bef0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
bf00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
bf10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
bf20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
bf30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
bf40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bf50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
bf60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
bf70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
bf80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
bf90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
bfa0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
bfb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
bfc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
bfd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
bfe0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
bff0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c000: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
c010: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
c020: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
c030: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
c040: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
c050: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
c060: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
c070: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
c080: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
c090: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
c0a0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
c0b0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
c0c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
c0d0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
c0e0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
c0f0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
c100: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
c110: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
c120: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
c130: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
c140: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
c150: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
c160: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
c170: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
c180: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
c190: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
c1a0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
c1b0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
c1c0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
c1d0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
c1e0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
c1f0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
c200: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c210: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
c220: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c230: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
c240: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
c250: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
c260: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
c270: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
c280: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c290: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
c2a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c2b0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
c2c0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
c2d0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
c2e0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
c2f0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
c300: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
c310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c320: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
c330: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
c340: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
c350: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
c360: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
c370: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
c380: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c390: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
c3a0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
c3b0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
c3c0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
c3d0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
c3e0: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
c3f0: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
c400: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
c410: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
c420: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
c430: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
c440: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
c450: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
c460: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
c470: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
c480: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
c490: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
c4a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
c4b0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
c4c0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
c4d0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
c4e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
c4f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c500: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
c510: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
c520: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
c530: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
c540: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
c550: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
c560: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
c570: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c580: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
c590: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
c5a0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
c5b0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
c5c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
c5d0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
c5e0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c5f0: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
c600: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
c610: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
c620: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
c630: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
c640: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
c650: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
c660: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
c670: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
c680: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
c690: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
c6a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
c6b0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
c6c0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
c6d0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
c6e0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
c6f0: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
c700: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
c710: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
c720: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
c730: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
c740: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
c750: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
c760: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
c770: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
c780: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
c790: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
c7a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
c7b0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
c7c0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
c7d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
c7e0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
c7f0: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
c800: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c810: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
c820: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
c830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
c840: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
c850: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
c860: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
c870: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
c880: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c890: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
c8a0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
c8b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
c8c0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
c8d0: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
c8e0: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
c8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
c900: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
c910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c920: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
c930: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
c940: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
c950: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
c960: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
c970: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
c980: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
c990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
c9a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
c9b0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
c9c0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
c9d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
c9e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
c9f0: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
ca00: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
ca10: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ca20: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
ca30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
ca40: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
ca50: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
ca60: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
ca70: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
ca80: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ca90: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
caa0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
cab0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cac0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
cad0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
cae0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
caf0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
cb00: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
cb10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
cb20: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
cb30: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
cb40: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
cb50: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
cb60: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
cb70: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
cb80: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
cb90: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
cba0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
cbb0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
cbc0: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
cbd0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
cbe0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
cbf0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
cc00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cc10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
cc20: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cc30: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
cc40: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
cc50: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
cc60: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
cc70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cc80: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
cc90: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
cca0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ccb0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ccc0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ccd0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
cce0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ccf0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
cd00: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
cd10: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
cd20: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
cd30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
cd40: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
cd50: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
cd60: 51 4c 49 54 45 5f 44 42 43 4f 4e 49 47 5f 4c 4f  QLITE_DBCONIG_LO
cd70: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
cd80: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
cd90: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
cda0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
cdb0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
cdc0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
cdd0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
cde0: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
cdf0: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
ce00: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
ce10: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
ce20: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
ce30: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
ce40: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
ce50: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
ce60: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
ce70: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
ce80: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
ce90: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
cea0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
ceb0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
cec0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
ced0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
cee0: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
cef0: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
cf00: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
cf10: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
cf20: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
cf30: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
cf40: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
cf50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cf60: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
cf70: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
cf80: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
cf90: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
cfa0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
cfb0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
cfc0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
cfd0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
cfe0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
cff0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
d000: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
d010: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d020: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
d030: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
d040: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
d050: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
d060: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
d070: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
d080: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
d090: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
d0a0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
d0b0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
d0c0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
d0d0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
d0e0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
d0f0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
d100: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
d110: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d120: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
d130: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
d140: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
d150: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
d160: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
d170: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
d180: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
d190: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
d1a0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
d1b0: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
d1c0: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
d1d0: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
d1e0: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
d1f0: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
d200: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
d210: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
d220: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
d230: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d240: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
d250: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
d260: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
d270: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
d280: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
d290: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
d2a0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
d2b0: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
d2c0: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
d2d0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
d2e0: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
d2f0: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
d300: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
d310: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
d320: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
d330: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
d340: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
d350: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
d360: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
d370: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
d380: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
d390: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
d3a0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
d3b0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
d3c0: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
d3d0: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
d3e0: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
d3f0: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
d400: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
d410: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
d420: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
d430: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
d440: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
d450: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
d460: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
d470: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
d480: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
d490: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
d4a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
d4b0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
d4c0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
d4d0: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
d4e0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
d4f0: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
d500: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
d510: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
d520: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
d530: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
d540: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
d550: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
d560: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
d570: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
d580: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
d590: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
d5a0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
d5b0: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
d5c0: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
d5d0: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
d5e0: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
d5f0: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
d600: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
d610: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
d620: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
d630: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
d640: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
d650: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
d660: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
d670: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
d680: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
d690: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
d6a0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
d6b0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
d6c0: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
d6d0: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
d6e0: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
d6f0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
d700: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
d710: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
d720: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
d730: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
d740: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
d750: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
d760: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
d770: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
d780: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
d790: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
d7a0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
d7b0: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
d7c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
d7d0: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
d7e0: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
d7f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
d800: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
d810: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
d820: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
d830: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
d840: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
d850: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
d860: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
d870: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
d880: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
d890: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
d8a0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
d8b0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
d8c0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
d8d0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d8e0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
d8f0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
d900: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
d910: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
d920: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
d930: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
d940: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
d950: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d960: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
d970: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d980: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d990: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d9a0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d9b0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d9c0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d9d0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d9e0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d9f0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
da00: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
da10: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
da20: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
da30: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
da40: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
da50: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
da60: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
da70: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
da80: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
da90: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
daa0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
dab0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
dac0: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
dad0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
dae0: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
daf0: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
db00: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
db10: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
db20: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
db30: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
db40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
db50: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
db60: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
db70: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
db80: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
db90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
dba0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
dbb0: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
dbc0: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
dbd0: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
dbe0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
dbf0: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
dc00: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
dc10: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
dc20: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
dc30: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
dc40: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
dc50: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
dc60: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
dc70: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
dc80: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
dc90: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
dca0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
dcb0: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
dcc0: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
dcd0: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
dce0: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
dcf0: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
dd00: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
dd10: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
dd20: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
dd30: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
dd40: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
dd50: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
dd60: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
dd70: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
dd80: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
dd90: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
dda0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
ddb0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
ddc0: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
ddd0: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
dde0: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
ddf0: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
de00: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
de10: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
de20: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
de30: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
de40: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
de50: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
de60: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
de70: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
de80: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
de90: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
dea0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
deb0: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
dec0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
ded0: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
dee0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
def0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
df00: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
df10: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
df20: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
df30: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
df40: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
df60: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
df70: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
df80: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
df90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
dfa0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
dfb0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
dfc0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
dfd0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
dfe0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
dff0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
e000: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
e010: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
e020: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
e030: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
e040: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
e050: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
e060: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
e070: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
e080: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
e090: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
e0a0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e0b0: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
e0c0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
e0d0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
e0e0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
e0f0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
e100: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e110: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
e120: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
e130: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
e140: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e150: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
e160: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
e170: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
e180: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
e190: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
e1a0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
e1b0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
e1c0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
e1d0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
e1e0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
e1f0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
e200: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
e210: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
e220: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
e230: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
e240: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
e250: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
e260: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
e270: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
e280: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
e290: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
e2a0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
e2b0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
e2c0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
e2d0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
e2e0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
e2f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
e300: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
e310: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
e320: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
e330: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
e340: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
e350: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
e360: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
e370: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
e380: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
e390: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
e3a0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
e3b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e3c0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
e3d0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
e3e0: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
e3f0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e400: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
e410: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
e420: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
e430: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e440: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
e450: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e460: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e470: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e480: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
e490: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
e4a0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
e4b0: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
e4c0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e4d0: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
e4e0: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
e4f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e500: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
e510: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
e520: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
e530: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
e540: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
e550: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
e560: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
e570: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
e580: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
e590: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
e5a0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
e5b0: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
e5c0: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
e5d0: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
e5e0: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
e5f0: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
e600: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
e610: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
e620: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
e630: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e640: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
e650: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
e660: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e670: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e680: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e690: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e6a0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e6b0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e6c0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
e6d0: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
e6e0: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
e6f0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
e700: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
e710: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
e720: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
e730: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
e740: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
e750: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
e760: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
e770: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
e780: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e790: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e7a0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e7b0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e7c0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e7d0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e7e0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e7f0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e800: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
e810: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
e820: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
e830: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
e840: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
e850: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
e860: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
e870: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
e880: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
e890: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
e8a0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
e8b0: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
e8c0: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
e8d0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
e8e0: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
e8f0: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
e900: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
e910: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
e920: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
e930: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
e940: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
e950: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e960: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
e970: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
e980: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
e990: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
e9a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
e9b0: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
e9c0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
e9d0: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
e9e0: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
e9f0: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
ea00: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
ea10: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
ea20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ea30: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
ea40: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
ea50: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
ea60: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
ea70: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
ea80: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
ea90: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
eaa0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
eab0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
eac0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
ead0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
eae0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
eaf0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
eb00: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
eb10: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
eb20: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
eb30: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
eb40: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
eb50: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
eb60: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
eb70: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
eb80: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
eb90: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
eba0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
ebb0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ebc0: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
ebd0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ebe0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
ebf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
ec00: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
ec10: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
ec20: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
ec30: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
ec40: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
ec50: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
ec60: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
ec70: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
ec80: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
ec90: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
eca0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
ecb0: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
ecc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ecd0: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
ece0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ecf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ed00: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
ed10: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
ed20: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
ed30: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ed40: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ed50: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
ed60: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
ed70: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
ed80: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
ed90: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
eda0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
edb0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
edc0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
edd0: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
ede0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
edf0: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
ee00: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
ee10: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
ee20: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
ee30: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
ee40: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
ee50: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
ee60: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
ee70: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
ee80: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
ee90: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
eea0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
eeb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
eec0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
eed0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
eee0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
eef0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
ef00: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
ef10: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
ef20: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
ef30: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
ef40: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
ef50: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
ef60: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
ef70: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
ef80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ef90: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
efa0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
efb0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
efc0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
efd0: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
efe0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
eff0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f000: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
f010: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f020: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
f030: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
f040: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
f050: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
f060: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f070: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
f080: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
f090: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f0a0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
f0b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
f0c0: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
f0d0: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
f0e0: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
f0f0: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
f100: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
f110: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
f120: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
f130: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
f140: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
f150: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f160: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f170: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f180: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
f190: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
f1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
f1b0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
f1c0: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
f1d0: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
f1e0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
f1f0: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
f200: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
f210: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
f220: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
f230: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
f240: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
f250: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
f260: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
f270: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
f280: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
f290: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
f2a0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
f2b0: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
f2c0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
f2d0: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
f2e0: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
f2f0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
f300: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
f310: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
f320: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
f330: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
f340: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
f350: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
f360: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
f370: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
f380: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
f390: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
f3a0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
f3b0: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
f3c0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
f3d0: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
f3e0: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
f3f0: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
f400: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
f410: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
f420: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
f430: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
f440: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
f450: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
f460: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
f470: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
f480: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
f490: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f4a0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
f4b0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
f4c0: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
f4d0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
f4e0: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
f4f0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f500: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
f510: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
f520: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
f530: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
f540: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
f550: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
f560: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
f570: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
f580: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
f590: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f5a0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
f5b0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
f5c0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
f5d0: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
f5e0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
f5f0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
f600: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
f610: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
f620: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
f630: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
f640: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
f650: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
f660: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
f670: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
f680: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
f690: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
f6a0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
f6b0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
f6c0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
f6d0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
f6e0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
f6f0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
f700: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
f710: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
f720: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
f730: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
f740: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
f750: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
f760: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
f770: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
f780: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
f790: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
f7a0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
f7b0: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
f7c0: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
f7d0: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
f7e0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
f7f0: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
f800: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
f810: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
f820: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
f830: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
f840: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
f850: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
f860: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
f870: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
f880: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
f890: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f8a0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
f8b0: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
f8c0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
f8d0: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
f8e0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
f8f0: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
f900: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
f910: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
f920: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
f930: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
f940: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
f950: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
f960: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
f970: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
f980: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
f990: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
f9a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
f9b0: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
f9c0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
f9d0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
f9e0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
f9f0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
fa00: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
fa10: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
fa20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fa30: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
fa40: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
fa50: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
fa60: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
fa70: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
fa80: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
fa90: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
faa0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
fab0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
fac0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
fad0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
fae0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
faf0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
fb00: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
fb10: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
fb20: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
fb30: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
fb40: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
fb50: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
fb60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
fb70: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
fb80: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
fb90: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
fba0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
fbb0: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
fbc0: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
fbd0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
fbe0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
fbf0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
fc00: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
fc10: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
fc20: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
fc30: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
fc40: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
fc50: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
fc60: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fc70: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
fc80: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
fc90: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
fca0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
fcb0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
fcc0: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
fcd0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
fce0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
fcf0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
fd00: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
fd10: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
fd20: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
fd30: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
fd40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
fd50: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
fd60: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
fd70: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
fd80: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
fd90: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
fda0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
fdb0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
fdc0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
fdd0: 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
fde0: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
fdf0: 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
fe00: 70 65 64 20 61 74 20 32 5e 31 32 2e 20 52 65 61  ped at 2^12. Rea
fe10: 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
fe20: 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
fe30: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
fe40: 65 20 61 72 65 20 32 5e 35 20 74 68 72 6f 75 67  e are 2^5 throug
fe50: 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  h 2^8.</dd>.**.*
fe60: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fe70: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
fe80: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
fe90: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
fea0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
feb0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
fec0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
fed0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
fee0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
fef0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
ff00: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
ff10: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ff20: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
ff30: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
ff40: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
ff50: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
ff60: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
ff70: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
ff80: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
ff90: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
ffa0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
ffb0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
ffc0: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
ffd0: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
ffe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
fff0: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
10000 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10010 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10020 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10030 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10040 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10050 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
10060 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
10070 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
10080 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
10090 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
100a0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
100b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
100c0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
100d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
100e0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
100f0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
10100 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
10110 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
10120 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
10130 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
10140 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10150 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10160 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10170 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10180 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
10190 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
101a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
101b0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
101c0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
101d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
101e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
101f0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10200 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10210 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
10220 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
10230 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
10240 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
10250 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
10260 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
10270 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
10280 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
10290 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
102a0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
102b0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
102c0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
102d0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
102e0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
102f0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10300 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10310 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10320 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10330 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
10340 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
10350 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
10360 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
10370 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
10380 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
10390 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
103a0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
103b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
103c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
103d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
103e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
103f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
10400 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10410 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
10420 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
10430 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
10440 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
10450 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
10460 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
10470 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68  llocation for th
10480 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
10490 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20  ry allocator on 
104a0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
104b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
104c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
104d0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
104e0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
104f0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
10500 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
10510 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
10520 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
10530 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
10540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
10550 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  ^  ^(This option
10560 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e   sets the.** <i>
10570 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
10580 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
10590 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
105a0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76  _LOOKASIDE].** v
105b0 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  erb to [sqlite3_
105c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
105d0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
105e0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
105f0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
10600 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
10610 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
10620 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
10630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
10640 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10650 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
10660 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
10670 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
10680 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
10690 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
106a0 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
106b0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
106c0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
106d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
106e0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
106f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10700 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
10710 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
10720 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
10730 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
10740 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
10750 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
10760 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
10770 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
10780 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
10790 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
107a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
107b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
107c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
107d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
107e0 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
107f0 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
10800 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
10810 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
10820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
10830 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
10840 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
10850 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
10860 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
10870 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
10880 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
10890 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
108a0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
108b0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
108c0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
108d0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
108e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
108f0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
10900 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
10910 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
10920 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
10930 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
10940 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
10950 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
10960 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
10970 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
10980 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
10990 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
109a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
109b0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
109c0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
109d0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
109e0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
109f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10a00 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
10a10 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
10a20 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
10a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10a40 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
10a50 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
10a60 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
10a70 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
10a80 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
10a90 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
10aa0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10ab0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
10ac0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
10ad0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10ae0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
10af0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
10b00 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
10b10 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
10b20 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
10b30 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
10b40 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10b50 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
10b60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
10b70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
10b80 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
10b90 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
10ba0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
10bb0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
10bc0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
10bd0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
10be0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
10bf0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
10c00 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
10c10 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
10c20 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
10c30 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
10c40 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
10c50 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10c60 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
10c70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10c80 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
10c90 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
10ca0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
10cb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
10cc0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10cd0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
10ce0 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
10cf0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
10d00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10d10 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
10d20 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10d40 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
10d50 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10d70 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
10d80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
10d90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
10db0 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
10dc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
10dd0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
10de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10df0 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
10e00 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
10e10 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
10e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10e30 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
10e40 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
10e50 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
10e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10e70 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
10e80 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
10e90 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
10ea0 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
10eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10ec0 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
10ed0 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
10ee0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10ef0 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
10f00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
10f10 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
10f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10f30 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
10f40 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
10f50 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
10f60 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
10f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
10f80 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
10f90 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
10fa0 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
10fb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10fc0 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
10fd0 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
10fe0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10ff0 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
11000 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
11010 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
11020 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11030 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
11040 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65     15  /* sqlite
11050 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
11060 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
11070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
11080 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
11090 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a  Func, void* */..
110a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
110b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
110c0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
110d0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
110e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
110f0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11100 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11110 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11120 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11130 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
11140 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11150 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
11160 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11170 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11180 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11190 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
111a0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
111b0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
111c0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
111d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
111e0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
111f0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11200 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11210 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11220 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11230 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11240 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
11250 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
11260 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
11270 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11280 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
11290 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
112a0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
112b0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
112c0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
112d0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
112e0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
112f0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
11300 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
11310 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11320 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
11330 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
11340 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
11350 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
11360 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
11370 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
11380 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
11390 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
113a0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
113b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
113c0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
113d0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
113e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
113f0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11400 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
11410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d  ointer to an mem
11420 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
11430 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
11440 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
11450 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
11460 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
11470 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
11480 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
11490 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
114a0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
114b0 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
114c0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
114d0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
114e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
114f0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
11500 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
11510 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
11520 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
11530 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
11540 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
11550 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
11560 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
11570 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
11580 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11590 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
115a0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
115b0 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
115c0 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
115d0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
115e0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
115f0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
11600 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
11610 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
11620 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
11630 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
11640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11650 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
11660 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
11670 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
11680 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
11690 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
116a0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
116b0 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
116c0 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
116d0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
116e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
116f0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
11700 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
11710 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
11720 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
11730 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
11740 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
11750 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
11760 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
11770 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
11780 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11790 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
117a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
117b0 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
117c0 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
117d0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
117e0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
117f0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
11800 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
11810 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
11820 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
11830 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
11840 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
11850 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
11860 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
11870 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
11880 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
11890 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
118a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
118b0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
118c0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
118d0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
118e0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
118f0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
11900 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
11910 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
11920 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
11930 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
11940 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
11950 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
11960 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
11970 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
11980 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
11990 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
119a0 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
119b0 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
119c0 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
119d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
119e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
119f0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
11a00 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
11a10 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
11a20 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
11a30 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
11a40 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
11a50 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
11a60 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
11a70 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
11a80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
11a90 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
11aa0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
11ab0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
11ac0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
11ad0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
11ae0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
11af0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
11b00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11b10 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
11b20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
11b30 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
11b40 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
11b50 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
11b60 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
11b70 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
11b80 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
11b90 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
11ba0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
11bb0 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
11bc0 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
11bd0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 65 72 73  o enable trigers
11be0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
11bf0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
11c00 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
11c10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
11c20 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
11c30 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
11c40 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
11c50 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
11c60 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
11c70 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
11c80 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
11c90 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
11ca0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
11cb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
11cc0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
11cd0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
11ce0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
11cf0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
11d00 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
11d10 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
11d20 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
11d30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
11d40 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
11d50 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
11d60 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
11d70 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
11d80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
11d90 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
11da0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
11db0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
11dc0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
11dd0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
11de0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
11df0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
11e00 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
11e10 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
11e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
11e30 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
11e40 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
11e50 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
11e60 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
11e70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
11e80 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
11e90 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
11ea0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
11eb0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
11ec0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
11ed0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
11ee0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
11ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
11f00 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
11f10 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
11f20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
11f30 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
11f40 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
11f50 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
11f60 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
11f70 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
11f80 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
11f90 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
11fa0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
11fb0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
11fc0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
11fd0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
11fe0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
11ff0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
12000 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
12010 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
12020 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
12030 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
12040 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
12050 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
12060 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
12070 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
12080 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
12090 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
120a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
120b0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
120c0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
120d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
120e0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
120f0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
12100 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
12110 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
12120 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
12130 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
12140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
12150 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12160 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
12170 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
12180 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
12190 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
121a0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
121b0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
121c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
121d0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
121e0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
121f0 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
12200 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
12210 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
12220 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
12230 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
12240 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
12250 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
12260 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
12270 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
12280 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
12290 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
122a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
122b0 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
122c0 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
122d0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
122e0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
122f0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
12300 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
12310 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
12320 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
12330 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
12340 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
12350 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
12360 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12370 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
12380 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
12390 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
123a0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
123b0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
123c0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
123d0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
123e0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
123f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
12400 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
12410 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
12420 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
12430 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
12440 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
12450 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12460 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
12470 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
12480 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
12490 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
124a0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
124b0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
124c0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
124d0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
124e0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
124f0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
12500 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
12510 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
12520 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
12530 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
12540 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
12550 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
12560 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
12570 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
12580 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
12590 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
125a0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
125b0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
125c0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
125d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
125e0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
125f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
12600 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12610 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12620 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
12630 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
12640 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
12650 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12660 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
12670 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12680 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
12690 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
126a0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
126b0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
126c0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
126d0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
126e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
126f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
12700 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
12710 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12720 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
12730 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
12740 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
12750 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12760 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
12770 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
12780 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
12790 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
127a0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
127b0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
127c0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
127d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
127e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
127f0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
12800 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
12810 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
12820 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
12830 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
12840 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
12850 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
12860 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
12870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
12880 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
12890 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
128a0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
128b0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
128c0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
128d0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
128e0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
128f0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
12900 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
12910 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
12920 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
12930 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
12940 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
12950 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12960 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
12970 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12980 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
12990 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
129a0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
129b0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
129c0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
129d0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
129e0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
129f0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
12a00 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
12a10 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
12a20 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
12a30 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
12a40 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12a50 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
12a60 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
12a70 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
12a80 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
12a90 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
12aa0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
12ab0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
12ac0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
12ad0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
12ae0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
12af0 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
12b00 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
12b10 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
12b20 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
12b30 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
12b40 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
12b50 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
12b60 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
12b70 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
12b80 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
12b90 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
12ba0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
12bb0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
12bc0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
12bd0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
12be0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
12bf0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
12c00 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
12c10 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12c20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
12c30 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
12c40 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
12c50 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
12c60 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
12c70 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
12c80 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
12c90 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
12ca0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
12cb0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
12cc0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
12cd0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
12ce0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
12cf0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
12d00 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
12d10 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
12d20 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
12d30 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
12d40 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
12d50 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
12d60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
12d70 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
12d80 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
12d90 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
12da0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
12db0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
12dc0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12dd0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
12de0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
12df0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
12e00 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
12e10 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
12e20 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
12e30 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
12e40 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
12e50 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
12e60 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
12e70 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
12e80 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
12e90 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
12ea0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
12eb0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
12ec0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
12ed0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
12ee0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
12ef0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
12f00 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
12f10 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
12f20 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
12f30 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
12f40 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
12f50 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
12f60 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
12f70 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
12f80 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
12f90 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
12fa0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
12fb0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
12fc0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
12fd0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
12fe0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
12ff0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
13000 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
13010 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
13020 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
13030 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
13040 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
13050 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
13060 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
13070 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
13080 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
13090 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
130a0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
130b0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
130c0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
130d0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
130e0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
130f0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
13100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13110 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
13120 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
13130 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
13140 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13150 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
13160 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
13170 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
13180 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
13190 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
131a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
131b0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
131c0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
131d0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
131e0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
131f0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
13200 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
13210 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
13220 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
13230 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
13240 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13250 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
13260 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
13270 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
13280 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13290 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
132a0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
132b0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
132c0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
132d0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
132e0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
132f0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13300 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
13310 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
13320 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13330 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
13340 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
13350 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
13360 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
13370 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
13380 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
13390 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
133a0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
133b0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
133c0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
133d0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
133e0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
133f0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
13400 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
13410 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
13420 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
13430 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
13440 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
13450 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
13460 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13470 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
13480 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
13490 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
134a0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
134b0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
134c0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
134d0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
134e0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
134f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
13500 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
13510 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
13520 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
13530 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
13540 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
13550 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
13560 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
13570 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
13580 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
13590 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
135a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
135b0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
135c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
135d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
135e0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
135f0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13600 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
13610 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
13620 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
13630 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
13640 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
13650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
13660 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
13670 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
13680 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
13690 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
136a0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
136b0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
136c0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
136d0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
136e0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
136f0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
13700 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
13710 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
13720 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
13730 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
13740 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
13750 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
13760 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
13770 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
13780 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
13790 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
137a0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
137b0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
137c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
137d0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
137e0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
137f0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
13800 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
13810 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
13820 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
13830 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
13840 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
13850 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
13860 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
13870 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
13880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
13890 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
138a0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
138b0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
138c0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
138d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
138e0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
138f0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
13900 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
13910 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
13920 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
13930 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
13940 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
13950 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
13960 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
13970 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
13980 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
13990 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
139a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
139b0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
139c0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
139d0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
139e0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
139f0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
13a00 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
13a10 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13a20 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
13a30 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
13a40 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
13a50 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
13a60 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
13a70 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
13a80 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
13a90 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
13aa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13ab0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
13ac0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
13ad0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
13ae0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
13af0 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
13b00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
13b10 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
13b20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
13b30 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
13b40 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
13b50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
13b60 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
13b70 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
13b80 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
13b90 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
13ba0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
13bb0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
13bc0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
13bd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
13be0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
13bf0 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
13c00 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
13c10 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
13c20 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
13c30 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
13c40 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
13c50 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
13c60 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
13c70 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
13c80 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
13c90 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
13ca0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
13cb0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
13cc0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
13cd0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
13ce0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
13cf0 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
13d00 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
13d10 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
13d20 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
13d30 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
13d40 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
13d50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13d60 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
13d70 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
13d80 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
13d90 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
13da0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
13db0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
13dc0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
13dd0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
13de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13df0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
13e00 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
13e10 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
13e20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
13e30 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
13e40 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
13e50 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
13e60 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
13e70 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
13e80 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
13e90 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
13ea0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
13eb0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
13ec0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
13ed0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
13ee0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
13ef0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
13f00 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
13f10 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
13f20 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
13f30 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
13f40 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
13f50 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
13f60 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
13f70 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
13f80 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
13f90 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
13fa0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
13fb0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
13fc0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
13fd0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
13fe0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
13ff0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
14000 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
14010 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
14020 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
14030 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
14040 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
14050 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
14060 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
14070 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
14080 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
14090 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
140a0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
140b0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
140c0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
140d0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
140e0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
140f0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
14100 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
14110 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
14120 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
14130 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
14140 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
14150 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
14160 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
14170 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
14180 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
14190 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
141a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
141b0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
141c0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
141d0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
141e0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
141f0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
14200 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
14210 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
14220 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
14230 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
14240 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
14250 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
14260 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
14270 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
14280 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
14290 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
142a0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
142b0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
142c0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
142d0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
142e0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
142f0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
14300 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
14310 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
14320 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
14330 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
14340 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14350 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
14360 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
14370 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14380 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
14390 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
143a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
143b0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
143c0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
143d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
143e0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
143f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14400 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
14410 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
14420 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
14430 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14440 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
14450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
14460 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
14470 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
14480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
14490 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
144a0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
144b0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
144c0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
144d0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
144e0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
144f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
14500 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
14510 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
14520 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
14530 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
14540 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
14550 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
14560 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
14570 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
14580 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
14590 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
145a0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
145b0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
145c0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
145d0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
145e0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
145f0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
14600 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
14610 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
14620 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
14630 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
14640 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
14650 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14660 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
14670 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
14680 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
14690 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
146a0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
146b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
146c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
146d0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
146e0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
146f0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14700 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
14710 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
14720 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
14730 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
14740 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
14750 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
14760 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14770 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
14780 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
14790 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
147a0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
147b0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
147c0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
147d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
147e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
147f0 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
14800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
14810 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
14820 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
14830 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
14840 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
14850 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
14860 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
14870 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
14880 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
14890 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
148a0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
148b0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
148c0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
148d0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
148e0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
148f0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
14900 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
14910 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
14920 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
14930 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
14940 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
14950 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
14960 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
14970 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
14980 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
14990 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
149a0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
149b0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
149c0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
149d0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
149e0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
149f0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
14a00 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
14a10 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
14a20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
14a30 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
14a40 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
14a50 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
14a60 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
14a70 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
14a80 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
14a90 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
14aa0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
14ab0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
14ac0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
14ad0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
14ae0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
14af0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
14b00 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
14b10 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
14b20 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
14b30 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
14b40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14b50 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
14b60 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
14b70 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
14b80 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
14b90 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
14ba0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
14bb0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
14bc0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
14bd0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
14be0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
14bf0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
14c00 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
14c10 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
14c20 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
14c30 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14c40 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
14c50 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
14c60 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
14c70 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
14c80 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
14c90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
14ca0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
14cb0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
14cc0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
14cd0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
14ce0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
14cf0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
14d00 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
14d10 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
14d20 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
14d30 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
14d40 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
14d50 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
14d60 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
14d70 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
14d80 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
14d90 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
14da0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
14db0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
14dc0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
14dd0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
14de0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
14df0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
14e00 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
14e10 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
14e20 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
14e30 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
14e40 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
14e50 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
14e60 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
14e70 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
14e80 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
14e90 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
14ea0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
14eb0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
14ec0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
14ed0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
14ee0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
14ef0 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
14f00 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
14f10 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
14f20 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
14f30 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
14f40 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
14f50 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
14f60 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
14f70 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
14f80 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
14f90 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
14fa0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
14fb0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
14fc0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
14fd0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
14fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
14ff0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
15000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15010 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
15020 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
15030 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
15040 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
15050 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
15060 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
15070 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
15080 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
15090 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
150a0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
150b0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
150c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
150d0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
150e0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
150f0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
15100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15110 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
15120 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
15130 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
15140 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
15150 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
15160 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
15170 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
15180 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
15190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
151a0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
151b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
151c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
151d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
151e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
151f0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
15200 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
15210 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15220 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
15230 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
15240 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15250 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
15260 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
15270 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
15280 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
15290 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
152a0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
152b0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
152c0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
152d0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
152e0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
152f0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
15300 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
15310 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
15320 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
15330 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
15340 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
15350 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
15360 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
15370 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
15380 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
15390 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
153a0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
153b0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
153c0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
153d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
153e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
153f0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
15400 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
15410 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
15420 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
15430 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
15440 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
15450 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
15460 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
15470 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15480 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15490 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
154a0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
154b0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
154c0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
154d0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
154e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
154f0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
15500 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
15510 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
15520 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
15530 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
15540 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
15550 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
15560 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
15570 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
15580 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
15590 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
155a0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
155b0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
155c0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
155d0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
155e0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
155f0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
15600 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
15610 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
15620 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
15630 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
15640 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
15650 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
15660 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
15670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
15680 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
15690 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
156a0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
156b0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
156c0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
156d0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
156e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
156f0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
15700 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
15710 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
15720 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
15730 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
15740 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
15750 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
15760 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
15770 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
15780 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
15790 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
157a0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
157b0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
157c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
157d0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
157e0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
157f0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
15800 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
15810 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
15820 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
15830 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
15840 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
15850 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
15860 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
15870 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
15880 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
15890 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
158a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
158b0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
158c0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
158d0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
158e0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
158f0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
15900 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
15910 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
15920 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
15930 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
15940 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
15950 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
15960 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
15970 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
15980 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
15990 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
159a0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
159b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
159c0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
159d0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
159e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
159f0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
15a00 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
15a10 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
15a20 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
15a30 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
15a40 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
15a50 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
15a60 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
15a70 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
15a80 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
15a90 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
15aa0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15ab0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15ac0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
15ad0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
15ae0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
15af0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15b00 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
15b10 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
15b20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
15b30 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
15b40 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
15b50 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
15b60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15b70 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
15b80 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
15b90 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
15ba0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
15bb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
15bc0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
15bd0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
15be0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
15bf0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
15c00 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
15c10 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
15c20 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
15c30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
15c50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
15c60 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
15c70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15c80 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
15c90 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
15ca0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
15cb0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
15cc0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
15cd0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
15ce0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
15cf0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
15d00 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15d10 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
15d20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
15d30 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
15d40 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
15d50 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
15d60 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
15d70 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
15d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
15d90 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
15da0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
15db0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
15dc0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
15dd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
15de0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
15df0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
15e00 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
15e10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
15e20 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
15e30 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
15e40 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
15e50 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
15e60 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
15e70 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
15e80 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
15e90 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
15ea0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
15eb0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
15ec0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
15ed0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
15ee0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
15ef0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
15f00 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
15f10 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
15f20 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
15f30 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
15f40 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
15f50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
15f60 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
15f70 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
15f80 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
15f90 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
15fa0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
15fb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
15fc0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
15fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
15fe0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
15ff0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
16000 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
16010 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
16020 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
16030 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
16040 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
16050 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
16060 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
16070 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
16080 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
16090 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
160a0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
160b0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
160c0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
160d0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
160e0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
160f0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
16100 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
16110 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
16120 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
16130 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
16140 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
16150 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
16160 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
16170 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
16180 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
16190 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
161a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
161b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
161c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
161d0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
161e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
161f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
16200 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
16210 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
16220 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
16230 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
16240 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
16250 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
16260 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
16270 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
16280 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
16290 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
162a0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
162b0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
162c0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
162d0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
162e0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
162f0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
16300 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
16310 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
16320 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
16330 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16340 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
16350 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
16360 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
16370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
16380 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
16390 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
163a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
163b0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
163c0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
163d0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
163e0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
163f0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
16400 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
16410 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16420 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
16430 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
16440 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
16450 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
16460 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
16470 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
16480 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
16490 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
164a0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
164b0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
164c0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
164d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
164e0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
164f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
16500 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
16510 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
16520 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
16530 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
16540 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
16550 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
16560 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
16570 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
16580 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
16590 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
165a0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
165b0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
165c0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
165d0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
165e0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
165f0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
16600 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16610 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
16620 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
16630 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
16640 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
16650 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
16660 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
16670 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
16680 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
16690 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
166a0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
166b0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
166c0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
166d0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
166e0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
166f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
16700 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
16710 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16720 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
16730 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
16740 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
16750 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16760 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
16770 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
16780 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
16790 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
167a0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
167b0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
167c0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
167d0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
167e0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
167f0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
16800 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
16810 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
16820 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
16830 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
16840 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16850 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
16860 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
16870 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
16880 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
16890 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
168a0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
168b0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
168c0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
168d0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
168e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
168f0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
16900 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16910 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
16920 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
16930 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
16940 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
16950 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
16960 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
16970 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
16980 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
16990 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
169a0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
169b0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
169c0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
169d0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
169e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
169f0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
16a00 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
16a10 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
16a20 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
16a30 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
16a40 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
16a50 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
16a60 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
16a70 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
16a80 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
16a90 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
16aa0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
16ab0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
16ac0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
16ad0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
16ae0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
16af0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
16b00 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
16b10 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
16b20 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
16b30 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
16b40 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
16b50 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
16b60 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
16b70 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
16b80 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
16b90 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
16ba0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
16bb0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
16bc0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
16bd0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
16be0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
16bf0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
16c00 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
16c10 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
16c20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
16c30 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
16c40 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
16c50 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16c60 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16c70 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
16c80 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
16c90 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
16ca0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16cb0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
16cc0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
16cd0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
16ce0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
16cf0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16d00 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
16d10 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
16d20 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
16d30 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
16d40 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
16d50 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
16d60 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
16d70 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
16d80 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
16d90 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
16da0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
16db0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
16dc0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
16dd0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
16de0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
16df0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
16e00 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
16e10 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
16e20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16e30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
16e40 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
16e50 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
16e60 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
16e70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16e80 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
16e90 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
16ea0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
16eb0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
16ec0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
16ed0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
16ee0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
16ef0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
16f00 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
16f10 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
16f20 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
16f30 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
16f40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16f50 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
16f60 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
16f70 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
16f80 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
16f90 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
16fa0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
16fb0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
16fc0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
16fd0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
16fe0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
16ff0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
17000 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
17010 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
17020 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
17030 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
17040 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
17050 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
17060 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
17070 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
17080 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
17090 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
170a0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
170b0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
170c0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
170d0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
170e0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
170f0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
17100 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17110 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17120 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
17130 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
17140 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
17150 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
17160 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
17170 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
17180 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
17190 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
171a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
171b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
171c0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
171d0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
171e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
171f0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
17200 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
17210 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
17220 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
17230 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
17240 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
17250 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
17260 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
17270 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
17280 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
17290 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
172a0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
172b0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
172c0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
172d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
172e0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
172f0 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
17300 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
17310 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
17320 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
17330 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
17340 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
17350 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
17360 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17370 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
17380 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
17390 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
173a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
173b0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
173c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
173d0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
173e0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
173f0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
17400 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
17410 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
17420 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
17430 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
17440 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17450 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17460 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17470 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
17480 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
17490 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
174a0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
174b0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
174c0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
174d0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
174e0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
174f0 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
17500 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
17510 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
17520 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
17530 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
17540 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
17550 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17560 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17570 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
17580 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
17590 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
175a0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
175b0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
175c0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
175d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
175e0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
175f0 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
17600 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17610 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
17620 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
17630 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
17640 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
17650 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17660 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17670 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
17680 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
17690 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
176a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
176b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
176c0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
176d0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
176e0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
176f0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
17700 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
17710 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
17720 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
17730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17740 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
17750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17760 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17770 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
17780 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
17790 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
177a0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
177b0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
177c0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
177d0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
177e0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
177f0 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
17800 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
17810 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
17820 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
17830 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
17840 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
17850 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17860 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17870 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17880 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
17890 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
178a0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
178b0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
178c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
178d0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
178e0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
178f0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17900 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17910 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17920 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17930 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17940 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17950 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17960 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17970 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17980 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
17990 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
179a0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
179b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
179c0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
179d0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
179e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
179f0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17a00 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17a10 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17a20 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17a30 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17a40 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17a50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17a60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17a70 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17a80 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
17a90 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17aa0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
17ab0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
17ac0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
17ad0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
17ae0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
17af0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
17b00 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
17b10 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17b20 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17b30 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17b40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b50 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
17b60 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17b70 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
17b80 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17b90 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
17ba0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
17bb0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
17bc0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
17bd0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
17be0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17bf0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
17c00 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
17c10 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17c20 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
17c30 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
17c40 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
17c50 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
17c60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
17c70 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17c80 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
17c90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
17ca0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
17cb0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17cc0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17cd0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
17ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
17cf0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17d00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17d10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17d20 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17d30 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
17d40 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
17d50 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
17d60 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
17d70 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
17d80 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
17d90 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
17da0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
17db0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
17dc0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
17dd0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
17de0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
17df0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
17e00 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
17e10 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
17e20 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
17e30 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
17e40 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
17e50 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
17e60 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
17e70 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
17e80 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
17e90 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
17ea0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
17eb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17ec0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
17ed0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
17ee0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
17ef0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
17f00 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
17f10 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
17f20 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
17f30 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
17f40 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
17f50 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
17f60 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
17f70 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
17f80 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
17f90 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
17fa0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
17fb0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
17fc0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
17fd0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
17fe0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
17ff0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
18000 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
18010 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
18020 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
18030 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
18040 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
18050 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18060 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
18070 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
18080 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18090 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
180a0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
180b0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
180c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
180d0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
180e0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
180f0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
18100 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
18110 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
18120 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
18130 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
18140 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18150 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18160 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
18170 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
18180 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
18190 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
181a0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
181b0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
181c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
181d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
181e0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
181f0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
18200 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
18210 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
18220 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
18230 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
18240 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
18250 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
18260 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
18270 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
18280 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
18290 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
182a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
182b0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
182c0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
182d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
182e0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
182f0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
18300 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
18310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
18320 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
18330 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18340 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
18350 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
18360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
18370 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
18380 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
18390 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
183a0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
183b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
183c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
183d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
183e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
183f0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
18400 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18410 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
18420 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
18430 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
18440 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18450 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18460 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18470 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
18480 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18490 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
184a0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
184b0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
184c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
184d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
184e0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
184f0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
18500 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
18510 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
18520 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
18530 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
18540 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
18550 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
18560 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
18570 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
18580 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
18590 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
185a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
185b0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
185c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
185d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
185e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
185f0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
18600 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18610 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
18620 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18630 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
18640 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
18650 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
18660 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
18670 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18680 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
18690 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
186a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
186b0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
186c0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
186d0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
186e0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
186f0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
18700 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
18710 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
18720 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
18730 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
18740 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
18750 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
18760 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
18770 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
18780 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18790 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
187a0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
187b0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
187c0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
187d0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
187e0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
187f0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
18800 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
18810 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
18820 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
18830 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
18840 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
18850 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
18860 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
18870 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
18880 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18890 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
188a0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
188b0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
188c0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
188d0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
188e0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
188f0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
18900 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
18910 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
18920 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
18930 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
18940 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
18950 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
18960 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
18970 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
18980 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
18990 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
189a0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
189b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
189c0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
189d0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
189e0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
189f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
18a00 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
18a10 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
18a20 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18a30 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
18a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18a50 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
18a60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
18a70 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
18a80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
18a90 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69  isters a authori
18aa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
18ab0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
18ac0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
18ad0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
18ae0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
18af0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
18b00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18b20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
18b30 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
18b40 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
18b50 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
18b60 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
18b70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18b80 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
18b90 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
18ba0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
18bb0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
18bc0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
18bd0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
18be0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
18bf0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
18c00 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
18c10 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
18c20 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
18c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18c40 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18c50 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
18c60 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
18c70 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
18c80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18c90 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
18ca0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
18cb0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
18cc0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
18cd0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
18ce0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
18cf0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
18d00 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
18d10 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
18d20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
18d30 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
18d40 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
18d50 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
18d60 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
18d70 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
18d80 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
18d90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18da0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
18db0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
18dc0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
18dd0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18de0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18df0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
18e00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18e10 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18e20 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18e30 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
18e40 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18e50 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18e60 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
18e70 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
18e80 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18e90 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
18ea0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
18eb0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
18ec0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
18ed0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
18ee0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
18ef0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
18f00 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
18f10 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
18f20 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
18f30 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
18f40 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
18f50 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
18f60 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
18f70 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
18f80 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
18f90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
18fa0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
18fb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
18fc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
18fd0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
18fe0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
18ff0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
19000 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
19010 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19020 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
19030 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
19040 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
19050 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
19060 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
19070 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
19080 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
19090 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
190a0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
190b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
190c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
190d0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
190e0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
190f0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
19100 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
19110 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
19120 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
19130 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
19140 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
19150 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
19160 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
19170 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
19180 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
19190 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
191a0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
191b0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
191c0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
191d0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
191e0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
191f0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
19200 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
19210 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
19220 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
19230 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
19240 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
19250 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
19260 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
19270 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
19280 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
19290 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
192a0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
192b0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
192c0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
192d0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
192e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
192f0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
19300 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
19310 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
19320 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
19330 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
19340 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
19350 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
19360 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
19370 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
19380 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
19390 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
193a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
193b0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
193c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
193d0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
193e0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
193f0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
19400 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19410 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
19420 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
19430 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
19440 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
19450 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
19460 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
19470 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
19480 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
19490 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
194a0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
194b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
194c0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
194d0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
194e0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
194f0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
19500 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
19510 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
19520 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
19530 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
19540 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
19550 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
19560 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
19570 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
19580 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
19590 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
195a0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
195b0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
195c0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
195d0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
195e0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
195f0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
19600 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
19610 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
19620 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
19630 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
19640 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
19650 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
19660 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
19670 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
19680 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
19690 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
196a0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
196b0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
196c0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
196d0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
196e0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
196f0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
19700 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
19710 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
19720 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
19730 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
19740 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
19750 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
19760 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
19770 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
19780 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
19790 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
197a0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
197b0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
197c0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
197d0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
197e0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
197f0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
19800 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
19810 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
19820 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
19830 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
19840 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
19850 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19870 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19880 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19890 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
198a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
198b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
198c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
198d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
198e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
198f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
19900 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
19910 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
19920 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
19930 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
19940 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
19950 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
19960 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
19970 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
19980 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
19990 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
199a0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
199b0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
199c0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
199d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
199e0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
199f0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
19a00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19a10 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
19a20 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
19a30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
19a40 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
19a50 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
19a60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19a70 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
19a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19a90 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
19aa0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
19ab0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
19ac0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
19ad0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
19ae0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
19af0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
19b00 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
19b10 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
19b20 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
19b30 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
19b40 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
19b50 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
19b60 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
19b70 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
19b80 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
19b90 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
19ba0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
19bb0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
19bc0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
19bd0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
19be0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
19bf0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
19c00 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
19c10 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
19c20 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
19c30 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
19c40 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
19c50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19c60 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
19c70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
19c80 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
19c90 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
19ca0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
19cb0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
19cc0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
19cd0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
19ce0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
19cf0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
19d00 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
19d10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
19d20 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
19d30 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
19d40 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
19d50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
19d60 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
19d70 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
19d80 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
19d90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
19da0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
19db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
19dc0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
19dd0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
19de0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
19df0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
19e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
19e10 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
19e20 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
19e30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
19e40 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
19e50 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
19e60 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19e70 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
19e80 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
19e90 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
19ea0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
19eb0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
19ec0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
19ee0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
19ef0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
19f00 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
19f10 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
19f20 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
19f30 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
19f40 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
19f50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19f60 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
19f70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
19f80 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
19f90 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
19fa0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
19fb0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
19fc0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
19fd0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
19fe0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
19ff0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
1a000 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a010 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
1a020 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
1a030 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
1a040 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
1a050 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1a060 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a070 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
1a080 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
1a090 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a0a0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
1a0b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1a0c0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
1a0d0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
1a0e0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
1a0f0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1a100 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1a110 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
1a120 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1a130 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1a140 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1a150 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1a160 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
1a170 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1a180 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1a190 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1a1a0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
1a1b0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
1a1c0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
1a1d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1f0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
1a200 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
1a210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a220 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
1a230 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
1a240 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1a250 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1a260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a270 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
1a280 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
1a290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1a2a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a2b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a2c0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
1a2d0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
1a2e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1a2f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a310 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
1a320 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
1a330 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1a340 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1a360 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
1a370 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
1a380 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1a390 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1a3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a3b0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
1a3c0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
1a3d0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1a3e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a400 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
1a410 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
1a420 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1a430 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1a440 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a450 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
1a460 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
1a470 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1a480 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a490 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
1a4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a4b0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1a4c0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a4d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a4e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
1a4f0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
1a500 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1a510 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1a520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a530 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
1a540 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
1a550 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1a560 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a580 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1a590 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
1a5a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a5b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a5d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1a5e0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
1a5f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a620 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
1a630 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
1a640 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1a650 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1a660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a670 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
1a680 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
1a690 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1a6a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a6c0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
1a6d0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
1a6e0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1a6f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a710 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
1a720 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
1a730 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1a740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a760 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
1a770 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
1a780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1a790 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1a7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a7b0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
1a7c0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
1a7d0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
1a7e0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
1a7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1a800 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
1a810 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
1a820 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1a830 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1a840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
1a850 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
1a860 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
1a870 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1a880 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
1a8a0 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
1a8b0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
1a8c0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
1a8d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
1a8f0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1a900 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
1a910 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1a920 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1a930 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
1a940 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1a950 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
1a960 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1a970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a980 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
1a990 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1a9a0 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
1a9b0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
1a9c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a9d0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
1a9e0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
1a9f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
1aa00 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
1aa10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aa20 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
1aa30 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
1aa40 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1aa50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aa60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aa70 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
1aa90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1aaa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1aab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1aac0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
1aad0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
1aae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1aaf0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1ab00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ab10 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
1ab20 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
1ab30 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ab40 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
1ab50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ab60 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
1ab70 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
1ab80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ab90 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
1aba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1abb0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
1abc0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
1abd0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
1abe0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
1abf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ac00 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
1ac10 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
1ac20 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
1ac30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ac40 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
1ac50 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
1ac60 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1ac70 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1ac80 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ac90 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1aca0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1acb0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1acc0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1acd0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1ace0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1acf0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1ad00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1ad10 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
1ad20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
1ad30 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
1ad40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1ad50 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
1ad60 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
1ad70 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
1ad80 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
1ad90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1ada0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
1adb0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
1adc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1add0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
1ade0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
1adf0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
1ae00 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
1ae10 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1ae20 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
1ae30 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
1ae40 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
1ae50 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
1ae60 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
1ae70 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
1ae80 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
1ae90 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
1aea0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
1aeb0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
1aec0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1aed0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1aee0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
1aef0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
1af00 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
1af10 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
1af20 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
1af30 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
1af40 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
1af50 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
1af60 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
1af70 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
1af80 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
1af90 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
1afa0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
1afb0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1afc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
1afd0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
1afe0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
1aff0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
1b000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
1b010 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
1b020 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
1b030 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
1b040 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
1b050 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
1b060 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
1b070 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
1b080 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1b090 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
1b0a0 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
1b0b0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
1b0c0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
1b0d0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
1b0e0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1b0f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
1b100 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
1b110 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
1b120 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
1b130 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
1b140 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
1b150 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1b160 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1b170 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1b180 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1b190 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1b1a0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1b1b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1b1c0 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1b1d0 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1b1e0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1b1f0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1b200 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1b210 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1b220 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1b230 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
1b240 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
1b250 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
1b260 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
1b270 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
1b280 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
1b290 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
1b2a0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1b2b0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1b2c0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
1b2d0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
1b2e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
1b2f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
1b300 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
1b310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b320 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
1b330 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1b340 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1b350 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1b360 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1b370 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1b380 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
1b390 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
1b3a0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
1b3b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1b3c0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
1b3d0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
1b3e0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
1b3f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
1b400 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1b410 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1b420 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1b430 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1b440 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1b450 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1b460 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
1b470 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
1b480 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
1b490 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
1b4a0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
1b4b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b4c0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
1b4d0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
1b4e0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
1b4f0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
1b500 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
1b510 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
1b520 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
1b530 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
1b540 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1b550 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
1b560 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
1b570 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
1b580 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
1b590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
1b5a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1b5b0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b5c0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
1b5d0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
1b5e0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
1b5f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
1b600 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
1b610 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
1b620 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
1b630 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
1b640 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
1b650 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
1b660 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
1b670 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
1b680 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
1b690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b6a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1b6b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1b6c0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
1b6d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1b6e0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1b6f0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1b700 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1b710 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b720 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1b730 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1b740 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1b750 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
1b760 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1b770 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1b780 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1b790 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1b7a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b7b0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1b7c0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1b7d0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
1b7e0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
1b7f0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1b800 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
1b810 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
1b820 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
1b830 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
1b840 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1b850 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1b860 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1b870 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b890 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1b8a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1b8b0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1b8c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b8d0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
1b8e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1b8f0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1b900 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1b910 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1b920 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1b930 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1b940 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1b950 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1b960 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1b970 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1b980 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1b990 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1b9a0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1b9b0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1b9c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1b9d0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1b9e0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
1b9f0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ba00 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1ba10 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1ba20 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1ba30 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1ba40 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1ba50 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1ba60 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
1ba70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
1ba80 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
1ba90 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1baa0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
1bab0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
1bac0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
1bad0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
1bae0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
1baf0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
1bb00 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
1bb10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
1bb20 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
1bb30 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1bb40 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1bb50 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1bb60 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1bb70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1bb80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1bb90 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1bba0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1bbb0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1bbc0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1bbd0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1bbe0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1bbf0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1bc00 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1bc10 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1bc20 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1bc30 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1bc40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1bc50 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1bc60 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1bc70 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1bc80 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1bc90 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1bca0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1bcb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1bcc0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1bcd0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1bce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1bcf0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1bd00 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1bd10 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1bd20 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1bd30 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1bd40 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1bd50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1bd60 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
1bd70 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
1bd80 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
1bd90 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1bda0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1bdb0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1bdc0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1bdd0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1bde0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1bdf0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1be00 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
1be10 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1be20 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f  DCACHE],.** and/
1be30 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1be40 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1be50 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1be60 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1be70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1be80 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1be90 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1bea0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1beb0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1bec0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1bed0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1bee0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1bef0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1bf00 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1bf10 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1bf20 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1bf30 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1bf40 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1bf50 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1bf60 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1bf70 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1bf80 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1bf90 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1bfa0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1bfb0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1bfc0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1bfd0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1bfe0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1bff0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1c000 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1c010 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1c020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c030 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1c040 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1c050 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1c060 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1c070 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1c080 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1c090 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1c0a0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1c0b0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1c0c0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1c0d0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1c0e0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1c0f0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1c100 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1c110 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1c120 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1c130 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1c140 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1c150 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1c160 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1c170 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1c180 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1c190 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1c1a0 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1c1b0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1c1c0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1c1d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1c1e0 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
1c1f0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1c200 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
1c210 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1c220 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  ECACHE] flags,.*
1c230 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1c240 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1c250 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c260 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1c270 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1c280 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1c290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1c2a0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1c2b0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1c2c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1c2d0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1c2e0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1c2f0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1c300 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1c310 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1c320 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1c330 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1c340 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1c350 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1c360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c370 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1c380 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1c390 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1c3a0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1c3b0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1c3c0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1c3d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1c3e0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1c3f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1c400 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1c410 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1c420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c430 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1c440 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1c450 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1c460 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1c470 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1c480 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1c490 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1c4a0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1c4b0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1c4c0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1c4d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1c4e0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1c4f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c500 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1c510 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1c520 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1c530 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1c540 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1c550 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1c560 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1c570 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1c580 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1c590 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1c5a0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1c5b0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1c5c0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1c5d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1c5e0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1c5f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c600 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1c610 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1c620 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1c630 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1c640 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1c650 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1c660 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1c670 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1c680 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1c690 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1c6a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1c6b0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1c6c0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1c6d0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1c6e0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1c6f0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1c700 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1c710 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1c720 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1c730 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c740 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1c750 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1c760 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1c770 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1c780 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1c790 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1c7a0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1c7b0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1c7c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1c7d0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1c7e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c7f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1c800 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1c810 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1c820 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1c830 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1c840 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1c850 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1c860 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1c870 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1c880 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1c890 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1c8a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1c8b0 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1c8c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1c8d0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1c8e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1c8f0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1c900 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1c910 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1c920 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1c930 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1c940 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1c950 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1c960 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1c970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c980 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1c990 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1c9a0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1c9b0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1c9c0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1c9d0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1c9e0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1c9f0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1ca00 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1ca10 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1ca20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1ca30 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1ca40 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1ca50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ca60 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1ca70 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1ca80 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1ca90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1caa0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1cab0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1cac0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1cad0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1cae0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1caf0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1cb00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1cb10 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1cb20 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1cb30 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1cb40 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1cb50 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1cb60 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1cb70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1cb80 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1cb90 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1cba0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1cbb0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1cbc0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1cbd0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1cbe0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1cbf0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1cc00 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1cc10 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1cc20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1cc30 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1cc40 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1cc50 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1cc60 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1cc70 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1cc80 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1cc90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1ccb0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1ccc0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1ccd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1cce0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1ccf0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1cd00 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1cd10 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1cd20 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1cd30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd40 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1cd50 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1cd60 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1cd70 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1cd80 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1cd90 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1cda0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1cdb0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1cdc0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1cdd0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1cde0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1cdf0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1ce00 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1ce10 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1ce20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ce30 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1ce40 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1ce50 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1ce60 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1ce70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ce80 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ce90 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1cea0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ceb0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1cec0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ced0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1cee0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1cef0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1cf00 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1cf10 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1cf20 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1cf30 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1cf40 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1cf50 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1cf60 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1cf70 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1cf80 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1cf90 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1cfa0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1cfb0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1cfc0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1cfd0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1cfe0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1cff0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1d000 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1d010 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1d020 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d030 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1d040 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1d050 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1d060 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1d070 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1d080 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1d090 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1d0a0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1d0b0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1d0c0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1d0d0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1d0e0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1d0f0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1d100 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1d110 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1d120 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1d130 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1d140 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1d150 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1d160 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1d170 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1d180 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1d190 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d1a0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1d1b0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1d1c0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1d1d0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1d1e0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1d1f0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1d200 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1d210 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1d220 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1d230 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1d240 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1d250 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1d260 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1d270 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1d280 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1d290 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1d2a0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1d2b0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1d2c0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1d2d0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1d2e0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1d2f0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1d300 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1d310 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1d320 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1d330 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1d340 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1d350 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1d360 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1d370 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1d380 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1d390 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1d3a0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1d3b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1d3c0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1d3d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d3e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1d3f0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1d400 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1d410 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1d420 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1d430 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1d440 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1d450 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1d460 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1d470 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1d480 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1d490 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1d4a0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1d4b0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1d4c0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1d4d0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1d4e0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1d4f0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1d500 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1d510 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1d520 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1d530 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1d540 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1d550 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1d560 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1d570 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1d580 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1d590 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1d5a0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1d5b0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1d5c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1d5d0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1d5e0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1d5f0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1d600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d610 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1d620 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1d630 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1d640 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1d650 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1d660 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1d670 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1d680 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1d690 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1d6a0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1d6b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1d6c0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1d6d0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1d6e0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1d6f0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1d700 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1d710 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1d720 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1d730 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1d740 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1d750 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1d760 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1d770 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1d780 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1d790 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1d7a0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1d7b0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1d7c0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1d7d0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1d7e0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1d7f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1d800 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1d810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d820 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1d830 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1d840 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1d850 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1d860 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1d870 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1d880 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1d890 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1d8a0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1d8b0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1d8c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1d8d0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1d8e0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1d8f0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
1d900 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
1d910 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
1d920 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
1d930 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
1d940 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
1d950 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
1d960 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
1d970 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
1d980 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
1d990 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
1d9a0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
1d9b0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
1d9c0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d9d0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
1d9e0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
1d9f0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
1da00 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
1da10 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
1da20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
1da30 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
1da40 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
1da50 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
1da60 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
1da70 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
1da80 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
1da90 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
1daa0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
1dab0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1dac0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
1dad0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
1dae0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1daf0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
1db00 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1db10 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
1db20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
1db30 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
1db40 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1db50 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
1db60 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
1db70 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
1db80 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1db90 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
1dba0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
1dbb0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
1dbc0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1dbd0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1dbe0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1dbf0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1dc00 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1dc10 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1dc20 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1dc30 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1dc40 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1dc50 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1dc60 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1dc70 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1dc80 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1dc90 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
1dca0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
1dcb0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
1dcc0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
1dcd0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
1dce0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
1dcf0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
1dd00 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
1dd10 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
1dd20 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
1dd30 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
1dd40 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
1dd50 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
1dd60 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
1dd70 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
1dd80 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
1dd90 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
1dda0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
1ddb0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
1ddc0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
1ddd0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
1dde0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
1ddf0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
1de00 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
1de10 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1de20 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
1de30 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
1de40 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
1de50 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
1de60 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
1de70 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
1de80 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
1de90 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
1dea0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
1deb0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
1dec0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
1ded0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
1dee0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
1def0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
1df00 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1df10 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
1df20 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1df30 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1df40 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1df50 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1df60 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1df70 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
1df80 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
1df90 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
1dfa0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1dfb0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1dfc0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
1dfd0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
1dfe0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
1dff0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
1e000 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e010 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1e020 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
1e030 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1e040 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1e050 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
1e060 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
1e070 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
1e080 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
1e090 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
1e0a0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
1e0b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  >.** ^(<dt>SQLIT
1e0c0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1e0d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e0e0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1e0f0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
1e100 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
1e110 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
1e120 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e130 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1e140 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1e150 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1e160 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
1e170 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
1e180 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e190 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e1a0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
1e1b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e1c0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1e1d0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
1e1e0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
1e1f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
1e200 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
1e210 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
1e220 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1e230 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
1e240 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
1e250 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
1e260 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
1e270 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1e280 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
1e290 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e2a0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1e2b0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
1e2c0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
1e2d0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
1e2e0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e2f0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1e300 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1e310 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e320 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1e330 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1e340 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
1e350 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1e360 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
1e370 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
1e380 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e390 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
1e3a0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
1e3b0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
1e3c0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
1e3d0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
1e3e0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
1e3f0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
1e400 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
1e410 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
1e420 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
1e430 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
1e440 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
1e450 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1e460 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e470 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1e480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e490 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1e4a0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1e4b0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
1e4c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1e4d0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1e4e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e4f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1e500 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
1e510 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
1e520 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e  .)^</dd>.**.** ^
1e530 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e540 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e550 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e560 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1e570 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1e580 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1e590 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
1e5a0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1e5b0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1e5c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e5d0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1e5e0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1e5f0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
1e600 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
1e610 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
1e620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
1e630 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1e640 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1e650 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1e660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1e670 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1e680 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1e690 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1e6a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1e6b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1e6c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e6d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1e6e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1e6f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1e700 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1e710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1e720 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1e730 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1e740 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1e750 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1e760 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1e770 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1e780 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1e790 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1e7a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1e7b0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1e7c0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1e7d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e7e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1e7f0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1e800 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e810 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1e820 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1e830 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e840 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1e850 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1e860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e870 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1e880 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1e890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e8a0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1e8b0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1e8c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e8d0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1e8e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1e8f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1e900 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1e910 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1e920 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1e930 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1e940 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1e950 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1e960 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1e970 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1e980 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1e990 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1e9a0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1e9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1e9c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1e9d0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1e9e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1e9f0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1ea00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1ea10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1ea20 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1ea30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ea40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1ea50 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1ea60 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1ea70 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1ea80 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1ea90 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1eaa0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1eab0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1eac0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1ead0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1eae0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1eaf0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1eb00 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1eb10 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1eb20 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1eb30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1eb40 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1eb50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1eb60 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1eb70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1eb80 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1eb90 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1eba0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1ebb0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1ebc0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1ebd0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1ebe0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1ebf0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1ec00 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1ec10 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1ec20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1ec30 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1ec40 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1ec50 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1ec60 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1ec70 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1ec80 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1ec90 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1eca0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1ecb0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1ecc0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1ecd0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1ece0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1ecf0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1ed00 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1ed10 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1ed20 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1ed30 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1ed40 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1ed50 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1ed60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1ed70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1ed80 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1ed90 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1eda0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1edb0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1edc0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1edd0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1ede0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1edf0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1ee00 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1ee10 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1ee20 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1ee30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1ee40 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1ee50 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1ee60 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1ee70 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1ee80 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1ee90 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1eea0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1eeb0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1eec0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1eed0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1eee0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1eef0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1ef00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1ef10 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1ef20 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1ef30 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1ef40 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1ef50 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1ef60 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1ef70 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1ef80 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1ef90 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1efa0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1efb0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1efc0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1efd0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1efe0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1eff0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1f000 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1f010 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1f020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1f030 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1f040 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1f050 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1f060 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1f070 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1f080 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1f090 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1f0a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1f0b0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1f0c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1f0d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1f0e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1f0f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f100 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1f110 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1f120 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1f130 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1f140 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1f150 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1f160 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1f170 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1f180 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f190 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1f1a0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1f1b0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1f1c0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1f1d0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1f1e0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1f1f0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1f200 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1f210 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1f220 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1f230 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1f240 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1f250 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1f260 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1f270 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1f280 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1f290 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1f2a0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1f2b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1f2c0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1f2d0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1f2e0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1f2f0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1f300 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1f310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f320 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1f330 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1f340 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1f350 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1f360 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f   it again..** </
1f370 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1f380 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
1f390 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
1f3a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1f3b0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1f3c0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
1f3d0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
1f3e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
1f3f0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
1f400 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
1f410 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
1f420 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
1f430 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
1f440 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
1f450 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
1f460 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
1f470 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
1f480 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1f490 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1f4a0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
1f4b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
1f4c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1f4d0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1f4e0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1f4f0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1f500 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1f510 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1f520 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1f530 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1f540 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1f550 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1f560 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
1f570 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
1f580 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
1f590 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1f5a0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
1f5b0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
1f5c0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
1f5d0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
1f5e0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
1f5f0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
1f600 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
1f610 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1f620 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
1f630 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
1f640 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
1f650 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
1f660 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
1f670 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
1f680 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
1f690 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1f6a0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
1f6b0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
1f6c0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
1f6d0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
1f6e0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
1f6f0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
1f700 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
1f710 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
1f720 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
1f730 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
1f740 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
1f750 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
1f760 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1f770 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
1f780 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
1f790 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
1f7a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
1f7b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
1f7c0 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT2] compile-t
1f7d0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
1f7e0 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a  abled..** the .*
1f7f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1f800 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f810 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1f820 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f830 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f840 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f850 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1f860 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1f870 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1f880 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1f890 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1f8a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1f8b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1f8c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1f8d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1f8e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1f8f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1f900 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1f910 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1f920 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1f930 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1f940 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1f950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1f960 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f970 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f980 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f9a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f9b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1f9c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f9d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f9e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f9f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1fa00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1fa10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1fa20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1fa30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1fa40 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1fa50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1fa60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1fa70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1fa80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1fa90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1faa0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1fab0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1fac0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1fad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1fae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1faf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1fb00 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1fb10 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1fb20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1fb30 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1fb40 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1fb50 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1fb60 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1fb70 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1fb80 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1fb90 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1fba0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1fbb0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1fbc0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1fbd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1fbe0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1fbf0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1fc00 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1fc10 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1fc20 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1fc30 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1fc40 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1fc50 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1fc60 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1fc70 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1fc80 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1fc90 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1fca0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1fcb0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1fcc0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1fcd0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1fce0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1fcf0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1fd00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1fd10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1fd20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1fd30 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1fd40 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1fd50 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1fd60 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1fd70 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1fd80 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1fd90 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1fda0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1fdb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fdc0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1fdd0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1fde0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1fdf0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1fe00 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1fe10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1fe20 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1fe30 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1fe40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1fe50 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1fe60 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1fe70 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1fe80 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
1fe90 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
1fea0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
1feb0 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
1fec0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1fed0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
1fee0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
1fef0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
1ff00 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
1ff10 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
1ff20 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
1ff30 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
1ff40 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
1ff50 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
1ff60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1ff70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1ff80 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
1ff90 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
1ffa0 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
1ffb0 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
1ffc0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
1ffd0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
1ffe0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
1fff0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
20000 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
20010 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
20020 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
20030 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
20040 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
20050 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
20060 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
20070 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
20080 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
20090 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
200a0 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
200b0 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
200c0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
200d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
200e0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
200f0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
20100 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
20110 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
20120 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
20130 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
20140 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
20150 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
20160 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
20170 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
20180 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
20190 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
201a0 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
201b0 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
201c0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
201d0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
201e0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
201f0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
20200 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
20210 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
20220 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
20230 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
20240 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
20250 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
20260 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
20270 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
20280 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
20290 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
202a0 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
202b0 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
202c0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
202d0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
202e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
202f0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
20300 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
20310 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
20320 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
20330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
20340 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
20350 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
20360 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
20370 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
20380 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
20390 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
203a0 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  isk..*/.int sqli
203b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
203c0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
203d0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
203e0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
203f0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
20400 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
20410 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
20420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
20430 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
20440 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
20450 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
20460 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20470 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
20480 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
20490 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
204a0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
204b0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
204c0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
204d0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
204e0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
204f0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
20500 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
20510 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
20520 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
20530 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
20540 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
20550 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
20560 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
20570 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
20580 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
20590 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
205a0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
205b0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
205c0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
205d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
205e0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
205f0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
20600 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
20610 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
20620 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20630 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
20640 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
20650 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
20660 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
20670 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
20680 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
20690 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
206a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
206b0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
206c0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
206d0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
206e0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
206f0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
20700 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
20710 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
20720 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
20730 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20740 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
20750 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
20760 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
20770 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20780 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
20790 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
207a0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
207b0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
207c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
207d0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
207e0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
207f0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
20800 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
20810 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
20820 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
20830 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
20840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
20850 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
20860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
20870 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
20880 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
20890 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
208a0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
208b0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
208c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
208d0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
208e0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
208f0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
20900 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
20910 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
20920 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
20930 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
20940 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
20950 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
20960 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
20970 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
20980 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20990 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
209a0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
209b0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
209c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
209d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
209e0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
209f0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
20a00 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
20a10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
20a20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
20a30 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
20a40 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
20a50 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
20a60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
20a70 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
20a80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
20a90 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
20aa0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
20ab0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20ac0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
20ad0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
20ae0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
20af0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
20b00 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
20b10 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
20b20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
20b30 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
20b40 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
20b50 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
20b60 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
20b70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20b80 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
20b90 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
20ba0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
20bb0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
20bc0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
20bd0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
20be0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
20bf0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
20c00 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
20c10 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
20c20 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
20c30 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
20c40 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
20c50 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20c60 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
20c70 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
20c80 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
20c90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20ca0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
20cb0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
20cc0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
20cd0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
20ce0 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
20cf0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
20d00 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
20d10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
20d20 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
20d30 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
20d40 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
20d50 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
20d60 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
20d70 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
20d80 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
20d90 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
20da0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
20db0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
20dc0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
20dd0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
20de0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
20df0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
20e00 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
20e10 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
20e20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
20e30 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
20e40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
20e50 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
20e60 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
20e70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
20e80 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
20e90 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
20ea0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
20eb0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
20ec0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
20ed0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20ee0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
20ef0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20f00 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
20f10 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
20f20 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
20f30 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
20f40 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
20f50 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
20f60 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
20f70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
20f80 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
20f90 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
20fa0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
20fb0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
20fc0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
20fd0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
20fe0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
20ff0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
21000 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
21010 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
21020 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
21030 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
21040 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
21050 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
21060 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
21070 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
21080 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
21090 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
210a0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
210b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
210c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
210d0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
210e0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
210f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
21100 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
21110 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
21120 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
21130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
21140 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
21150 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
21160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21170 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
21180 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
21190 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
211a0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
211b0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
211c0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
211d0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
211e0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
211f0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
21200 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
21210 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
21220 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
21230 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
21240 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
21250 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
21260 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
21270 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
21280 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
21290 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
212a0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
212b0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
212c0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
212d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
212e0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
212f0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
21300 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
21310 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
21320 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
21330 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
21340 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
21350 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
21360 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
21370 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
21380 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
21390 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
213a0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
213b0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
213c0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
213d0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
213e0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
213f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21400 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
21410 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
21420 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
21430 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
21440 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
21450 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
21460 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
21470 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
21480 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
21490 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
214a0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
214b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
214c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
214d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
214e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
214f0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
21500 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
21510 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
21520 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
21530 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
21540 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
21550 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
21560 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
21570 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
21580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21590 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
215a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
215b0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
215c0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
215d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
215e0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
215f0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
21600 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
21610 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
21620 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
21630 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
21640 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
21650 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
21660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21670 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
21680 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
21690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
216a0 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
216b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
216c0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
216d0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
216e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
216f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
21700 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
21710 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
21720 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
21730 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
21740 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
21750 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
21760 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
21770 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
21780 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
21790 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
217a0 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
217b0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
217c0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
217d0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
217e0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
217f0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
21800 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
21810 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
21820 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
21830 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
21840 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
21850 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
21860 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
21870 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
21880 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
21890 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
218a0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
218b0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
218c0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
218d0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
218e0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
218f0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
21900 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
21910 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
21920 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
21930 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
21940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
21950 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
21960 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
21970 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
21980 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
21990 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
219a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
219b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
219c0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
219d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
219e0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
219f0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
21a00 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
21a10 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
21a20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
21a30 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
21a40 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
21a50 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
21a60 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
21a70 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
21a80 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
21a90 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
21aa0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
21ab0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
21ac0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
21ad0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
21ae0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
21af0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
21b00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21b10 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
21b20 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
21b30 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
21b40 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
21b50 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
21b60 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
21b70 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
21b80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21b90 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
21ba0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
21bb0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21bc0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
21bd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
21be0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
21bf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
21c00 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
21c10 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
21c20 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
21c30 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
21c40 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
21c50 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
21c60 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
21c70 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
21c80 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
21c90 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
21ca0 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
21cb0 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
21cc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21cd0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21ce0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21cf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21d00 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
21d10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21d20 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21d30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
21d40 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
21d50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
21d60 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
21d70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
21d80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21d90 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
21da0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
21db0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
21dc0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
21dd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
21de0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
21df0 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
21e00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
21e10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
21e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21e30 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
21e40 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
21e50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21e60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21e70 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
21e80 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
21e90 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
21ea0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21eb0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21ec0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
21ed0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
21ee0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
21ef0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
21f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21f10 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
21f20 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
21f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
21f40 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
21f50 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
21f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21f70 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
21f80 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
21f90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
21fa0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
21fb0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
21fc0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
21fd0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
21fe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21ff0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
22000 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
22010 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
22020 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
22030 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
22040 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
22050 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
22060 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
22070 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
22080 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
22090 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
220a0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
220b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
220c0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
220d0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
220e0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
220f0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
22100 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
22110 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
22120 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
22130 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
22140 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
22150 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
22160 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
22170 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
22180 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
22190 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
221a0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
221b0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
221c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
221d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
221e0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
221f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22200 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
22210 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22220 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22230 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
22240 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22250 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
22260 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
22270 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
22280 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
22290 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  r.**.** ^The sql
222a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
222b0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
222c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
222d0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
222e0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
222f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
22300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22310 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
22320 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
22330 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
22340 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
22350 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
22360 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
22370 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
22380 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
22390 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
223a0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
223b0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
223c0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
223d0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
223e0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
223f0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
22400 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
22410 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
22420 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
22430 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
22440 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
22450 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
22460 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
22470 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
22480 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
22490 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
224a0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
224b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
224c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
224d0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
224e0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
224f0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
22500 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
22510 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
22520 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
22530 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
22540 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
22550 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
22560 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
22570 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
22580 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
22590 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
225a0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
225b0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
225c0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
225d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
225e0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
225f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
22600 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
22610 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
22620 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22630 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22640 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
22650 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22660 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
22670 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22680 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22690 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
226a0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
226b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
226c0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
226d0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
226e0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
226f0 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
22700 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
22710 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
22720 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
22730 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
22740 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
22750 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
22760 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
22770 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22780 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
22790 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
227a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
227b0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
227c0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
227d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
227e0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
227f0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
22800 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
22810 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
22820 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
22830 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
22840 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22850 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
22860 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22880 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22890 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
228a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
228b0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
228c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
228d0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
228e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
228f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22900 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
22910 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
22920 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
22930 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
22940 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
22950 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
22960 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  ent.**.** ^Contr
22970 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
22980 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
22990 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
229a0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
229b0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
229c0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
229d0 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
229e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
229f0 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
22a00 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
22a10 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
22a20 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  s to NULL..*/.in
22a30 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f  t sqlite3_clear_
22a40 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
22a50 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
22a60 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
22a70 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41   Of Columns In A
22a80 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
22a90 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75  * ^Return the nu
22aa0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22ab0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
22ac0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
22ad0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
22ae0 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73  tatement]. ^This
22af0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22b00 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61   0 if pStmt is a
22b10 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  n SQL.** stateme
22b20 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  nt that does not
22b30 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f   return data (fo
22b40 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50  r example an [UP
22b50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  DATE])..**.** Se
22b60 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22b70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a  _data_count()].*
22b80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
22b90 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
22ba0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
22bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22bc0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
22bd0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
22be0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
22bf0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22c00 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
22c10 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
22c20 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
22c30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
22c40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
22c50 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
22c60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
22c70 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
22c80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22c90 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22ca0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
22cb0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
22cc0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
22cd0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
22ce0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
22cf0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
22d00 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
22d10 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22d20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22d30 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
22d40 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
22d50 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
22d60 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
22d70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22d80 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
22d90 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
22da0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
22db0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
22dc0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
22dd0 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
22de0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
22df0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22e00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
22e10 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
22e20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22e30 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
22e40 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
22e50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22e60 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
22e70 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
22e80 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
22e90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
22ea0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
22eb0 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
22ec0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
22ed0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
22ee0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
22ef0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
22f00 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
22f10 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
22f20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
22f30 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
22f40 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
22f50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
22f60 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
22f70 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
22f80 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
22f90 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
22fa0 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
22fb0 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
22fc0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
22fd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
22fe0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
22ff0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
23000 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
23010 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
23020 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
23030 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23050 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23060 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
23070 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23080 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
23090 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
230a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
230b0 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
230c0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
230d0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
230e0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
230f0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
23100 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
23110 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
23120 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
23130 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
23140 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
23150 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
23160 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
23170 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
23180 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
23190 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
231a0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
231b0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
231c0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
231d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
231e0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
231f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23200 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
23210 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
23220 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
23230 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
23240 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
23250 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
23260 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
23270 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
23280 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
23290 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
232a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
232b0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
232c0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
232d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
232e0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
232f0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
23300 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
23310 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
23320 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
23330 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
23340 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
23350 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
23360 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
23370 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
23380 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
23390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
233a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
233b0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
233c0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
233d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
233e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
233f0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
23400 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
23410 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
23420 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
23430 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
23440 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
23450 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
23460 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
23470 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
23480 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
23490 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
234a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
234b0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
234c0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
234d0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
234e0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
234f0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
23500 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
23510 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
23520 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
23530 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
23540 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
23550 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
23560 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
23570 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
23580 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
23590 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
235a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
235b0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
235c0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
235d0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
235e0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
235f0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
23600 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
23610 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
23620 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
23630 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
23640 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
23650 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
23660 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
23670 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
23680 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
23690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
236a0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
236b0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
236c0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
236d0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
236e0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
236f0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
23700 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
23710 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
23720 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
23730 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
23740 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
23750 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
23760 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
23770 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
23780 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
23790 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
237a0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
237b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
237c0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
237d0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
237e0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
237f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
23800 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
23810 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
23820 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
23830 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
23840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
23850 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
23860 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
23870 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
23880 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
23890 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
238a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
238b0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
238c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
238d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
238e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
238f0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
23900 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23910 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
23920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
23930 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
23940 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
23950 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
23960 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
23970 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23980 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
23990 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
239a0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
239b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
239c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
239d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
239e0 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
239f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23a00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23a10 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
23a20 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
23a30 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
23a40 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23a50 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
23a60 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
23a70 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
23a80 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
23a90 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
23aa0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
23ab0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
23ac0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
23ad0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
23ae0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
23af0 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
23b00 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
23b10 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
23b20 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
23b30 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
23b40 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
23b50 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23b60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
23b70 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
23b80 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
23b90 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
23ba0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
23bb0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
23bc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
23bd0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
23be0 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
23bf0 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
23c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
23c10 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
23c20 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
23c30 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
23c40 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
23c50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
23c60 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
23c70 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
23c80 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
23c90 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
23ca0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
23cb0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
23cc0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
23cd0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
23ce0 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
23cf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
23d00 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
23d10 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
23d20 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
23d30 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
23d40 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
23d50 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
23d60 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
23d70 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
23d80 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
23d90 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
23da0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
23db0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
23dc0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
23dd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
23de0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
23df0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
23e00 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
23e10 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
23e20 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
23e30 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
23e40 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
23e50 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
23e60 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
23e70 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
23e80 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
23e90 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23ea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
23eb0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
23ec0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
23ed0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
23ee0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
23ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23f00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23f10 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
23f20 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
23f30 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
23f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23f50 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
23f60 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
23f70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
23f80 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
23f90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23fa0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
23fb0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
23fc0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
23fd0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
23fe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23ff0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
24000 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
24010 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
24020 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
24030 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
24040 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
24050 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
24060 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
24070 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
24080 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
24090 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
240a0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
240b0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
240c0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
240d0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
240e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
240f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
24100 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
24110 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
24120 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
24130 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
24140 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
24150 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
24160 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
24170 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
24180 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
24190 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
241a0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
241b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
241c0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
241d0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
241e0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
241f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
24200 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
24210 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
24220 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
24230 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
24240 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
24250 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
24260 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
24270 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
24280 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
24290 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
242a0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
242b0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
242c0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
242d0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
242e0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
242f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
24300 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
24310 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
24320 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
24330 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
24340 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
24350 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
24360 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
24370 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
24380 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
24390 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
243a0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
243b0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
243c0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
243d0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
243e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
243f0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
24400 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
24410 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
24420 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
24430 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
24440 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
24450 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
24460 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
24470 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
24480 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
24490 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
244a0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
244b0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
244c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
244d0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
244e0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
244f0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
24500 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
24510 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
24520 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
24530 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
24540 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
24550 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
24560 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
24570 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
24580 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
24590 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
245a0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
245b0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
245c0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
245d0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
245e0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
245f0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
24600 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
24610 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
24620 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
24630 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
24640 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
24650 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
24660 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
24670 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
24680 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
24690 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
246a0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
246b0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
246c0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
246d0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
246e0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
246f0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
24700 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
24710 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
24720 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
24730 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
24740 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
24750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
24760 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
24770 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
24780 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
24790 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
247a0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
247b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
247c0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
247d0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
247e0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
247f0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
24800 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
24810 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
24820 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
24830 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24840 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
24850 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
24860 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
24870 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
24880 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
24890 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
248a0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
248b0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
248c0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
248d0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
248e0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
248f0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
24900 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
24910 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
24920 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
24930 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
24940 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
24950 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
24960 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
24970 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
24980 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
24990 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
249a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
249b0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
249c0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
249d0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
249e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
249f0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
24a00 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
24a10 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
24a20 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
24a30 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
24a40 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
24a50 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
24a60 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
24a70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
24a80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
24a90 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
24aa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
24ab0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
24ac0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
24ad0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
24ae0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
24af0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
24b00 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
24b10 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
24b20 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
24b30 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
24b40 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
24b50 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
24b60 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
24b70 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
24b80 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
24b90 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
24ba0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
24bb0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
24bc0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
24bd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
24be0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
24bf0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
24c00 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
24c10 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
24c20 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
24c30 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
24c40 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
24c50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
24c60 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
24c70 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
24c80 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
24c90 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
24ca0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
24cb0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
24cc0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
24cd0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
24ce0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
24cf0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
24d00 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
24d10 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
24d20 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
24d30 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
24d40 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
24d50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
24d60 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
24d70 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
24d80 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
24d90 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
24da0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
24db0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
24dc0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
24dd0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
24de0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
24df0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
24e00 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
24e10 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
24e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24e30 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
24e40 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
24e50 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
24e60 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
24e70 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
24e80 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
24e90 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
24ea0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
24eb0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
24ec0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
24ed0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
24ee0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
24ef0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
24f00 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
24f10 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
24f20 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
24f30 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
24f40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24f50 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
24f60 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
24f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24f80 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
24f90 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
24fa0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
24fb0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
24fc0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
24fd0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
24fe0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
24ff0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
25000 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
25010 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
25020 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
25030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
25040 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
25050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25060 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
25070 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
25080 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
25090 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
250a0 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
250b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
250c0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
250d0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
250e0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
250f0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
25100 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
25110 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
25120 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
25130 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
25140 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
25150 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
25160 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
25170 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
25180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
25190 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
251a0 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
251b0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
251c0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
251d0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
251e0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
251f0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
25200 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
25210 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  inter..**.** See
25220 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25230 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
25240 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
25250 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
25260 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25280 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
25290 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
252a0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
252b0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
252c0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
252d0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
252e0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
252f0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
25300 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
25310 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
25320 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
25330 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
25340 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
25350 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
25360 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
25370 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
25380 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
25390 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
253a0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
253b0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
253c0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
253d0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
253e0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
253f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
25400 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
25410 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
25420 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
25430 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
25440 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
25450 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
25460 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25470 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
25480 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
25490 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
254a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
254b0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
254c0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
254d0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
254e0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
254f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
25500 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
25510 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
25520 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
25530 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
25540 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
25550 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
25560 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
25570 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
25580 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
25590 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
255a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
255b0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
255c0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
255d0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
255e0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
255f0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
25600 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
25610 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
25620 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
25630 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
25640 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
25650 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
25660 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
25670 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
25680 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25690 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
256a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
256b0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
256c0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
256d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
256e0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
256f0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
25700 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25710 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
25720 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
25730 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
25740 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
25750 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
25760 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
25770 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
25780 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
25790 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
257a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
257b0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
257c0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
257d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
257e0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
257f0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
25800 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
25810 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
25820 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
25830 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
25840 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
25850 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
25860 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
25870 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
25880 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
25890 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
258a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
258b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
258c0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
258d0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
258e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
258f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25900 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
25910 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
25920 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
25930 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
25940 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25950 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
25960 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
25970 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
25980 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
25990 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
259a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
259b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
259c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
259d0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
259e0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
259f0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
25a00 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
25a10 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
25a20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
25a30 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
25a40 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
25a50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25a60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
25a70 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
25a80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
25a90 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
25aa0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
25ab0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
25ac0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
25ad0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
25ae0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
25af0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
25b00 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
25b10 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
25b20 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
25b30 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
25b40 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
25b50 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
25b60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
25b70 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
25b80 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
25b90 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
25ba0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
25bb0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
25bc0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
25bd0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
25be0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
25bf0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
25c00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25c10 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
25c20 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
25c30 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
25c40 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
25c50 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
25c60 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
25c70 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
25c80 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
25c90 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
25ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
25cb0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
25cc0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
25cd0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
25ce0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
25cf0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
25d00 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
25d10 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
25d20 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
25d30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
25d40 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
25d50 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
25d60 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
25d70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
25d80 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
25d90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
25da0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
25db0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
25dc0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25dd0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
25de0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
25df0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
25e00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
25e10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
25e20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
25e30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25e40 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
25e50 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
25e60 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
25e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25e80 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
25e90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
25ea0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
25eb0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
25ec0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
25ed0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
25ee0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25ef0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
25f00 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
25f10 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
25f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25f30 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
25f40 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
25f50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
25f60 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
25f70 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
25f80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25f90 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
25fa0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
25fb0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25fc0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
25fd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
25fe0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
25ff0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
26000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26010 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
26020 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
26030 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
26040 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
26050 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
26060 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
26070 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
26080 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
26090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
260a0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
260b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
260c0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
260d0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
260e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
260f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
26100 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26110 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
26120 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
26130 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
26140 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26150 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
26160 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
26170 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
26180 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26190 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
261a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
261b0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
261c0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
261d0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
261e0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
261f0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
26200 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
26210 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
26220 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
26230 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
26240 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26250 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
26260 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
26270 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
26280 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
26290 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
262a0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
262b0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
262c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
262d0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
262e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
262f0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
26300 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
26310 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
26320 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
26330 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
26340 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
26350 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
26360 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
26370 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
26380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
26390 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
263a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
263b0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
263c0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
263d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
263e0 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
263f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26400 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
26410 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
26420 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
26430 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
26440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26450 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
26460 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
26470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26480 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
26490 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
264a0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
264b0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
264c0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
264d0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
264e0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
264f0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
26500 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
26510 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
26520 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26530 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
26540 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26550 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26570 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
26580 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
26590 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
265a0 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
265b0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
265c0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
265d0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
265e0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
265f0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
26600 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
26610 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
26620 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
26630 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
26640 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
26650 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
26660 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
26670 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
26680 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
26690 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
266a0 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
266b0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
266c0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
266d0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
266e0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
266f0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
26700 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
26710 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
26720 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
26730 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
26740 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
26750 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26760 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
26770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26780 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
26790 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
267a0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
267b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
267c0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
267d0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
267e0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
267f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
26800 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
26810 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
26820 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
26830 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
26840 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
26850 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
26860 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
26870 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
26880 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
26890 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
268a0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
268b0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
268c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
268d0 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
268e0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
268f0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
26900 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
26910 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
26920 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26930 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
26940 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
26950 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26960 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
26970 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
26980 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
26990 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
269a0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
269b0 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
269c0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
269d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
269e0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
269f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
26a00 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
26a10 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
26a20 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
26a30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
26a40 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
26a50 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
26a60 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
26a70 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26a80 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26a90 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26aa0 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26ab0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
26ac0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
26ad0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26ae0 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
26af0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
26b00 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
26b10 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
26b20 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
26b30 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
26b40 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
26b50 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
26b60 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
26b70 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
26b80 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
26b90 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
26ba0 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
26bb0 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
26bc0 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
26bd0 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
26be0 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
26bf0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
26c00 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
26c10 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
26c20 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
26c30 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
26c40 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
26c50 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
26c60 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
26c70 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
26c80 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
26c90 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
26ca0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
26cb0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
26cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26cd0 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
26ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26cf0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
26d00 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
26d10 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
26d20 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
26d30 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
26d40 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
26d50 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
26d60 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
26d70 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
26d80 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
26d90 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
26da0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
26db0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
26dc0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
26dd0 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
26de0 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
26df0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
26e00 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
26e10 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
26e20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
26e30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
26e40 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
26e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
26e60 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
26e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26e80 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
26e90 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
26ea0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
26eb0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
26ec0 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
26ed0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
26ee0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
26ef0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
26f00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
26f10 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
26f20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26f30 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
26f40 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
26f50 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
26f60 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
26f70 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
26f80 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
26f90 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
26fa0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
26fb0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
26fc0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
26fd0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
26fe0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
26ff0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
27000 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27010 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
27020 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
27030 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
27040 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
27050 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
27060 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
27070 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
27080 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
27090 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
270a0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
270b0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
270c0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
270d0 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
270e0 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
270f0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
27100 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
27110 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
27120 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
27130 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
27140 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
27150 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
27160 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
27170 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
27180 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
27190 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
271a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
271b0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
271c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
271d0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
271e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
271f0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
27200 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
27210 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
27220 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
27230 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
27240 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
27250 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
27260 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
27270 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
27280 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
27290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
272a0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
272b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
272c0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
272d0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
272e0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
272f0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
27300 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27310 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
27320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27330 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
27340 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
27350 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
27360 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
27370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27380 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
27390 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
273a0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
273b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
273c0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
273d0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
273e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
273f0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
27400 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
27410 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27420 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
27430 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
27440 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
27450 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
27460 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
27470 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
27480 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
27490 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
274a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
274b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
274c0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
274d0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
274e0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
274f0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
27500 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
27510 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
27520 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
27530 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
27540 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
27550 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27560 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27570 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
27580 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
27590 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
275a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
275b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
275c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
275d0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
275e0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
275f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
27600 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
27610 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
27620 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
27630 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
27640 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
27650 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
27660 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
27670 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
27680 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
27690 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
276a0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
276b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
276c0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
276d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
276e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
276f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27700 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
27710 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27730 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
27740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27750 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
27760 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
27770 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
27780 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
27790 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
277a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
277b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
277c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
277d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
277e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
277f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
27800 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27810 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
27820 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
27830 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
27840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27850 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
27860 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
27870 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
27880 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
27890 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
278a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
278b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
278c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
278d0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
278e0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
278f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
27900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27910 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
27920 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27930 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
27940 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
27950 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
27960 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
27970 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
27980 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
27990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
279a0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
279b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
279c0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
279d0 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20  ors or.** or if 
279e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
279f0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
27a00 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
27a10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
27a20 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
27a30 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
27a40 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
27a50 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
27a60 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
27a70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
27a80 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
27a90 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
27aa0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
27ab0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
27ac0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
27ad0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
27ae0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
27af0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
27b00 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
27b10 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
27b20 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
27b30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
27b40 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
27b50 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
27b60 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
27b70 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
27b80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
27b90 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
27ba0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
27bb0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27bc0 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
27bd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
27be0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
27bf0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
27c00 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
27c10 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
27c20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
27c30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
27c40 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
27c50 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
27c60 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
27c70 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
27c80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27c90 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
27ca0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
27cb0 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
27cc0 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
27cd0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
27ce0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
27cf0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
27d00 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
27d10 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
27d20 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
27d30 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
27d40 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
27d50 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
27d60 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
27d70 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
27d80 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
27d90 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
27da0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
27db0 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
27dc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27dd0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
27de0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27df0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27e00 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
27e10 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
27e20 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
27e30 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
27e40 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
27e50 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
27e60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27e70 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
27e80 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
27e90 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
27ea0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
27eb0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
27ec0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
27ed0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
27ee0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
27ef0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
27f00 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
27f10 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
27f20 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
27f30 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
27f40 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
27f50 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
27f60 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
27f70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
27f80 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
27f90 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
27fa0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27fb0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
27fc0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
27fd0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
27fe0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
27ff0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
28000 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28010 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
28020 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28030 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
28040 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
28050 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
28060 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
28070 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
28080 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
28090 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
280a0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
280b0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
280c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
280d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
280e0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
280f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
28100 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
28110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28120 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
28130 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
28140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
28150 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
28160 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
28170 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
28180 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
28190 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
281a0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
281b0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
281c0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
281d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
281e0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
281f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28200 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
28210 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
28220 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
28230 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28240 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
28250 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
28260 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
28270 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
28280 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
28290 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
282a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
282b0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
282c0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
282d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
282e0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
282f0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
28300 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
28310 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
28320 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
28330 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
28340 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
28350 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
28360 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
28370 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
28380 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
28390 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
283a0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
283b0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
283c0 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
283d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
283e0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
283f0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
28400 72 0a 2a 2a 20 74 68 65 20 74 68 65 20 73 65 63  r.** the the sec
28410 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
28420 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
28430 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
28440 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
28450 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
28460 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
28470 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
28480 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
28490 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
284a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
284b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
284c0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
284d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
284e0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
284f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
28500 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
28510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
28520 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
28530 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28540 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
28550 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28560 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
28570 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
28580 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
28590 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
285a0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
285b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
285c0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
285d0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
285e0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
285f0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
28600 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
28610 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
28620 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
28630 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
28640 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
28650 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
28660 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
28670 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
28680 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
28690 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
286a0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
286b0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
286c0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
286d0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
286e0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
286f0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
28700 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
28710 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
28720 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
28730 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
28740 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28750 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
28760 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
28770 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
28780 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28790 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
287a0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
287b0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
287c0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
287d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
287e0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
287f0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
28800 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
28810 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
28820 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
28830 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
28840 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28850 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
28860 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
28870 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
28880 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
28890 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
288a0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
288b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
288c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
288d0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
288e0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
288f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
28900 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
28910 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
28920 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
28930 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
28940 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
28950 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28960 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
28970 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
28980 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
28990 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
289a0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
289b0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
289c0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
289d0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
289e0 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
289f0 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
28a00 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
28a10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28a20 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
28a30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28a40 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
28a50 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
28a60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
28a70 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
28a80 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
28a90 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
28aa0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
28ab0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
28ac0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
28ad0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
28ae0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
28af0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
28b00 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
28b10 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
28b20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
28b30 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
28b40 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
28b50 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
28b60 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
28b70 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
28b80 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
28b90 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
28ba0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
28bb0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
28bc0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
28bd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
28be0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
28bf0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
28c00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
28c10 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
28c20 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
28c30 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
28c40 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
28c50 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
28c60 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
28c70 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
28c80 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
28c90 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
28ca0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
28cb0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
28cc0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
28cd0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
28ce0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
28cf0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
28d00 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
28d10 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
28d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
28d30 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
28d40 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
28d50 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
28d60 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
28d70 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
28d80 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
28d90 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
28da0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28db0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28dc0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
28dd0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
28de0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
28df0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
28e00 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
28e10 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
28e20 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
28e30 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
28e40 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73 20  ss NULL poiners 
28e50 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
28e60 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  nction.** callba
28e70 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  cks..**.** ^(If 
28e80 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  the ninth parame
28e90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
28ea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
28eb0 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  2() is not NULL,
28ec0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64  .** then it is d
28ed0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
28ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
28ef0 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20  ta pointer. .** 
28f00 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
28f10 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
28f20 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  he function is d
28f30 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62  eleted, either b
28f40 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c  y being.** overl
28f50 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68  oaded or when th
28f60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
28f70 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a  ction closes.)^.
28f80 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  ** ^The destruct
28f90 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b  or is also invok
28fa0 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74  ed if the call t
28fb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  o.** sqlite3_cre
28fc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
28fd0 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65  ) fails..** ^Whe
28fe0 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  n the destructor
28ff0 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
29000 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72   tenth parameter
29010 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a   is invoked, it.
29020 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73  ** is passed a s
29030 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
29040 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f  hich is a copy o
29050 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
29060 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74  n data .** point
29070 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65  er which was the
29080 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
29090 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
290a0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
290b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
290c0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
290d0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
290e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
290f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
29100 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
29110 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
29120 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
29130 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
29140 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
29150 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
29160 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
29170 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
29180 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
29190 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
291a0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
291b0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
291c0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
291d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
291e0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
291f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
29200 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
29210 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
29220 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
29230 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
29240 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
29250 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
29260 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
29270 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
29280 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
29290 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
292a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
292b0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
292c0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
292d0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
292e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
292f0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
29300 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
29310 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
29320 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
29330 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
29340 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
29350 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
29360 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
29370 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
29380 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
29390 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
293a0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
293b0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
293c0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
293d0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
293e0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
293f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29400 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  ions..**.** ^An 
29410 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29420 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
29430 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c  permitted to cal
29440 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  l other.** SQLit
29450 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48  e interfaces.  H
29460 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c  owever, such cal
29470 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63  ls must not.** c
29480 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
29490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72  e connection nor
294a0 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73   finalize or res
294b0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a  et the prepared.
294c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  ** statement in 
294d0 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69  which the functi
294e0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
294f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
29500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
29510 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
29520 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
29530 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
29540 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
29550 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
29560 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
29570 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
29580 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
29590 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
295a0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
295b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
295c0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
295d0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
295e0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
295f0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
29600 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29610 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
29620 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
29630 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
29640 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
29650 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
29660 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
29670 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
29680 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
29690 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
296a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
296b0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
296c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
296d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
296e0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
296f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
29700 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
29710 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
29720 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
29730 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
29740 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
29750 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
29760 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
29770 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
29780 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
29790 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
297a0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
297b0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
297c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
297d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
297e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
297f0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
29800 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
29810 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
29820 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
29830 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
29840 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
29850 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
29860 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
29870 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
29880 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
29890 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
298a0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
298b0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
298c0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
298d0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
298e0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
298f0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
29900 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
29910 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
29920 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
29930 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
29940 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
29950 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
29960 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
29970 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
29980 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
29990 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
299a0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
299b0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
299c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
299d0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
299e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
299f0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
29a00 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
29a10 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
29a20 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
29a30 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
29a40 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
29a50 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
29a60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
29a70 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
29a80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
29a90 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
29aa0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
29ab0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
29ac0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
29ad0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
29ae0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
29af0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
29b00 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
29b10 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
29b20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
29b30 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
29b40 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
29b50 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
29b60 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
29b70 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
29b80 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29b90 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
29ba0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
29bb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
29bc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
29bd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
29be0 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
29bf0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
29c00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
29c10 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
29c20 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
29c30 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
29c40 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
29c50 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
29c60 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
29c70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
29c80 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
29c90 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
29ca0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
29cb0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
29cc0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
29cd0 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
29ce0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
29cf0 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
29d00 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
29d10 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
29d20 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
29d30 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
29d40 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
29d50 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
29d60 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
29d70 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
29d80 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
29d90 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
29da0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
29db0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
29dc0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
29dd0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
29de0 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
29df0 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
29e00 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
29e10 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
29e20 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
29e30 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
29e40 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
29e50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29e60 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
29e70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29e80 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
29e90 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
29ea0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
29eb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
29ec0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
29ed0 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
29ee0 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
29ef0 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
29f00 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
29f10 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
29f20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29f30 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
29f40 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
29f50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
29f60 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
29f70 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
29f80 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
29f90 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
29fa0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
29fb0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
29fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29fd0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
29fe0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
29ff0 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2a000 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2a010 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2a020 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2a030 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2a040 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2a050 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2a060 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2a070 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2a080 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2a090 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2a0a0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2a0b0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2a0c0 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
2a0d0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
2a0e0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
2a0f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2a100 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2a110 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2a120 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
2a130 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
2a140 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2a150 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2a160 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2a170 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2a180 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2a190 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2a1a0 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2a1b0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2a1c0 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2a1d0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2a1e0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2a1f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2a200 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2a210 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
2a220 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
2a230 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65   interfaces.** e
2a240 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74  xtract UTF-16 st
2a250 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64  rings as big-end
2a260 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65  ian and little-e
2a270 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65  ndian respective
2a280 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2a290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2a2a0 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
2a2b0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2a2c0 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
2a2d0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
2a2e0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
2a2f0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
2a300 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
2a310 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
2a320 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
2a330 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
2a340 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
2a350 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
2a360 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
2a370 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
2a380 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
2a390 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
2a3a0 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
2a3b0 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
2a3c0 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
2a3d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
2a3e0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
2a3f0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
2a400 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2a410 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
2a420 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2a430 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
2a440 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
2a450 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50  urned.)^.**.** P
2a460 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2a470 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2a480 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2a490 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2a4a0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2a4b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2a4c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2a4d0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2a4e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2a4f0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2a500 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2a510 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2a520 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a530 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2a540 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2a550 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2a560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a570 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2a580 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a590 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2a5a0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2a5b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2a5c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2a5d0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2a5e0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2a5f0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2a600 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2a610 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ers..*/.const vo
2a620 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2a630 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2a640 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2a650 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2a660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2a680 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2a690 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2a6a0 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2a6b0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2a6c0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2a6d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2a6e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a6f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2a710 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2a720 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2a730 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2a740 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2a750 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2a760 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2a770 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2a780 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2a790 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a7a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2a7b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a7c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a7e0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2a7f0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2a800 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2a810 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2a820 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2a830 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2a840 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2a850 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2a860 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2a870 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2a880 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
2a890 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
2a8a0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2a8b0 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
2a8c0 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
2a8d0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
2a8e0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
2a8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2a900 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
2a910 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2a920 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2a930 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
2a940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2a950 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
2a960 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
2a970 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
2a980 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2a990 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
2a9a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2a9b0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
2a9c0 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
2a9d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2a9e0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2a9f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2aa00 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2aa10 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2aa20 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
2aa30 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
2aa40 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2aa50 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
2aa60 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2aa70 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
2aa80 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
2aa90 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
2aaa0 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
2aab0 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
2aac0 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
2aad0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
2aae0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
2aaf0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
2ab00 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
2ab10 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
2ab20 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
2ab30 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
2ab40 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2ab50 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
2ab60 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
2ab70 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
2ab80 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
2ab90 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
2aba0 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
2abb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2abc0 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
2abd0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
2abe0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
2abf0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
2ac00 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
2ac10 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
2ac20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2ac30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2ac40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ac50 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
2ac60 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
2ac70 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
2ac80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
2ac90 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
2aca0 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
2acb0 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
2acc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
2acd0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2ace0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
2acf0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
2ad00 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
2ad10 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
2ad20 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
2ad30 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
2ad40 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
2ad50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
2ad60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2ad70 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
2ad80 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2ad90 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
2ada0 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
2adb0 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
2adc0 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
2add0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
2ade0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
2adf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
2ae00 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
2ae10 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ae20 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
2ae30 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
2ae40 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
2ae50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2ae60 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
2ae70 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2ae80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2ae90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2aea0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2aeb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2aec0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
2aed0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
2aee0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2aef0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2af00 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
2af10 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2af20 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2af30 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2af40 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2af50 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2af60 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2af70 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2af80 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2af90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2afa0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2afb0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
2afc0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
2afd0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
2afe0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  or Functions.**.
2aff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b000 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65  user_data() inte
2b010 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2b020 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
2b030 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
2b040 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61  the pUserData pa
2b050 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68  rameter (the 5th
2b060 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2b070 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2b080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b090 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2b0a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b0b0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2b0c0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2b0d0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2b0e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2b0f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2b100 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b110 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2b120 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2b130 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2b140 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2b150 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b160 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2b170 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2b180 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
2b190 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
2b1a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2b1b0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2b1c0 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
2b1d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b1e0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2b1f0 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2b200 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2b210 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2b220 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2b230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b240 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2b250 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2b260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b270 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2b280 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2b290 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2b2a0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2b2b0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2b2c0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2b2d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2b2e0 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74  nction..*/.sqlit
2b2f0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
2b300 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
2b310 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2b320 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b330 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
2b340 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20  iary Data.**.** 
2b350 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
2b360 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
2b370 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
2b380 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
2b390 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
2b3a0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
2b3b0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
2b3c0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
2b3d0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
2b3e0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
2b3f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2b400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
2b410 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
2b420 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
2b430 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
2b440 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
2b450 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
2b460 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
2b470 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
2b480 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
2b490 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
2b4a0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
2b4b0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
2b4c0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
2b4d0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
2b4e0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2b4f0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
2b500 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
2b510 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2b520 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
2b530 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
2b540 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
2b550 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
2b560 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
2b570 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
2b580 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
2b590 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
2b5a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2b5b0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
2b5c0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
2b5d0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
2b5e0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2b5f0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
2b600 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
2b610 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
2b620 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2b630 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2b640 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2b650 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61   to the metadata
2b660 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62  .** associated b
2b670 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  y the sqlite3_se
2b680 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63  t_auxdata() func
2b690 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74  tion with the Nt
2b6a0 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61  h argument.** va
2b6b0 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69  lue to the appli
2b6c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b6d0 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20  unction. ^If no 
2b6e0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
2b6f0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
2b700 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
2b710 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
2b720 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
2b730 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2b740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
2b750 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
2b760 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
2b770 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
2b780 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
2b790 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
2b7a0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
2b7b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
2b7c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2b7d0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2b7e0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2b7f0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2b800 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2b810 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2b820 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2b830 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2b840 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2b850 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b860 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2b870 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2b880 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2b890 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2b8a0 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2b8b0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2b8c0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e   destroyed..** ^
2b8d0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2b8e0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2b8f0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2b900 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2b910 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2b920 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2b930 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2b940 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2b950 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2b960 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2b970 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2b980 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2b990 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2b9a0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2b9b0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2b9c0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2b9d0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2b9e0 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2b9f0 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2ba00 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2ba10 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2ba20 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2ba30 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e  y time.  ^The on
2ba40 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2ba50 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2ba60 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2ba70 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2ba80 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2ba90 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  pped..**.** ^(In
2baa0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
2bab0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
2bac0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
2bad0 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
2bae0 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
2baf0 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
2bb00 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
2bb10 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
2bb20 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
2bb30 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29  d [parameters].)
2bb40 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ^.**.** These ro
2bb50 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2bb60 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2bb70 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2bb80 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2bb90 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2bba0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2bbb0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2bbc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2bbd0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
2bbe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2bbf0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2bc00 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
2bc10 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
2bc20 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
2bc30 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
2bc40 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
2bc50 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
2bc60 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65  havior.**.** The
2bc70 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
2bc80 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
2bc90 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2bca0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2bcb0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2bcc0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2bcd0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2bce0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e  sult_blob()].  ^
2bcf0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
2bd00 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
2bd10 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
2bd20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
2bd30 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
2bd40 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
2bd50 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
2bd60 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
2bd70 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2bd80 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65  destroyed.  ^The
2bd90 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
2bda0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
2bdb0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
2bdc0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
2bdd0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
2bde0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
2bdf0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
2be00 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
2be10 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
2be20 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
2be30 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
2be40 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
2be50 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
2be60 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
2be70 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
2be80 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
2be90 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
2bea0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
2beb0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
2bec0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2bed0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
2bee0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
2bef0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
2bf00 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
2bf10 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
2bf20 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
2bf30 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
2bf40 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
2bf50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
2bf60 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
2bf70 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
2bf80 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
2bf90 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2bfa0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
2bfb0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
2bfc0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
2bfd0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
2bfe0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2bff0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
2c000 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c010 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
2c020 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c030 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
2c040 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2c050 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
2c060 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
2c070 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
2c080 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
2c090 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
2c0a0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
2c0b0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
2c0c0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
2c0d0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
2c0e0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
2c0f0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
2c100 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
2c110 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
2c120 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2c130 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
2c140 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2c150 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
2c160 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2c170 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
2c180 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c190 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2c1a0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
2c1b0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
2c1c0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
2c1d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2c1e0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
2c1f0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
2c200 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
2c210 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
2c220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c230 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2c240 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
2c250 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
2c260 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2c270 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c280 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
2c290 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
2c2a0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
2c2b0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
2c2c0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
2c2d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
2c2e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
2c2f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c300 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
2c310 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2c320 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
2c330 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
2c340 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c350 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
2c360 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2c370 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2c380 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
2c390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c3a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c3b0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2c3c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2c3d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
2c3e0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
2c3f0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
2c400 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
2c410 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
2c420 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
2c430 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
2c440 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
2c450 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
2c460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2c470 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2c480 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
2c490 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
2c4a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
2c4b0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
2c4c0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
2c4d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
2c4e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2c4f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
2c500 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
2c510 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2c520 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
2c530 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c540 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
2c550 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
2c560 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
2c570 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2c580 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2c590 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2c5a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c5b0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
2c5c0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2c5d0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
2c5e0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2c5f0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
2c600 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2c610 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2c620 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2c630 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c640 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c650 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c660 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2c670 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
2c680 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
2c690 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
2c6a0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
2c6b0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
2c6c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2c6d0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
2c6e0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
2c6f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c700 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
2c710 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2c720 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
2c730 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
2c740 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
2c750 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
2c760 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
2c770 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
2c780 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
2c790 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
2c7a0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
2c7b0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
2c7c0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
2c7d0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
2c7e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c7f0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
2c800 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
2c810 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
2c820 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
2c830 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
2c840 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
2c850 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
2c860 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
2c870 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
2c880 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
2c890 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2c8a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c8b0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2c8c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2c8d0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
2c8e0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
2c8f0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
2c900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c910 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2c920 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2c930 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2c940 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2c950 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2c960 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2c970 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
2c980 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2c990 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2c9a0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
2c9b0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2c9c0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
2c9d0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
2c9e0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
2c9f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
2ca00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ca10 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
2ca20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ca30 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2ca40 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
2ca50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ca60 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
2ca70 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
2ca80 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
2ca90 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
2caa0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
2cab0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2cac0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
2cad0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
2cae0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
2caf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2cb00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cb10 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
2cb20 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2cb30 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
2cb40 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
2cb50 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2cb60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2cb70 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
2cb80 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2cb90 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2cba0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2cbb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2cbc0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2cbd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2cbe0 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
2cbf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2cc00 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
2cc10 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
2cc20 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
2cc30 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
2cc40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
2cc50 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
2cc60 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
2cc70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2cc80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
2cc90 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
2cca0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
2ccb0 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
2ccc0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2ccd0 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
2cce0 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
2ccf0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
2cd00 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2cd10 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
2cd20 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
2cd30 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
2cd40 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
2cd50 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
2cd60 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
2cd70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2cd80 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
2cd90 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
2cda0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2cdb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2cdc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2cdd0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2cde0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
2cdf0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
2ce00 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2ce10 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
2ce20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2ce30 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2ce40 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
2ce50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2ce60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2ce70 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
2ce80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
2ce90 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
2cea0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
2ceb0 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
2cec0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
2ced0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
2cee0 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
2cef0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2cf00 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
2cf10 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
2cf20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2cf30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2cf40 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2cf50 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2cf60 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2cf70 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
2cf80 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2cf90 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
2cfa0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
2cfb0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2cfc0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
2cfd0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
2cfe0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
2cff0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2d000 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
2d010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2d020 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d030 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2d040 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
2d050 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2d060 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
2d070 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
2d080 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
2d090 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
2d0a0 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
2d0b0 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
2d0c0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
2d0d0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
2d0e0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
2d0f0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
2d100 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
2d110 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
2d120 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
2d130 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2d140 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2d150 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2d160 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d170 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d180 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2d190 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2d1a0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2d1b0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2d1c0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
2d1d0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
2d1e0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
2d1f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
2d200 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
2d210 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
2d220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2d230 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
2d240 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2d250 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2d260 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2d270 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
2d280 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
2d290 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2d2a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
2d2b0 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70  copy the.** [unp
2d2c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d2d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73  _value] object s
2d2e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2d2f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
2d300 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
2d310 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2d320 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
2d330 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
2d340 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2d350 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  so that the [sql
2d360 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63  ite3_value] spec
2d370 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72  ified in the par
2d380 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67  ameter may chang
2d390 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c  e or.** be deall
2d3a0 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c  ocated after sql
2d3b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2d3c0 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68  e() returns with
2d3d0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20  out harm..** ^A 
2d3e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d3f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d400 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
2d410 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
2d420 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2d430 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d440 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
2d450 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
2d460 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
2d470 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
2d480 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
2d490 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
2d4a0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
2d4b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2d4c0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
2d4d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
2d4e0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
2d4f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2d500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d510 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
2d520 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
2d530 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2d540 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
2d550 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2d560 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20  efined..*/.void 
2d570 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2d580 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2d590 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d5a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2d5b0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2d5c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
2d5d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
2d5e0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76  ext*, double);.v
2d5f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d600 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2d610 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d620 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f   char*, int);.vo
2d630 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d640 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65  t_error16(sqlite
2d650 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d660 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  t void*, int);.v
2d670 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d680 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2d690 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d6a0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d6b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
2d6c0 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  em(sqlite3_conte
2d6d0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2d6e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2d6f0 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  code(sqlite3_con
2d700 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2d710 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d720 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
2d730 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  text*, int);.voi
2d740 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d750 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
2d760 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2d770 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71  _int64);.void sq
2d780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
2d790 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  l(sqlite3_contex
2d7a0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2d7b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71  3_result_text(sq
2d7c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d7d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2d7e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2d7f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d800 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
2d810 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d820 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2d830 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2d840 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d850 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2d860 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d870 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2d880 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2d890 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2d8a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2d8b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d8c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2d8d0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2d8e0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2d8f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
2d900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d910 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2d920 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d930 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
2d940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d950 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2d960 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65  CAPI3REF: Define
2d970 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53   New Collating S
2d980 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e  equences.**.** ^
2d990 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2d9a0 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20  add, remove, or 
2d9b0 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74  modify a [collat
2d9c0 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a  ion] associated.
2d9d0 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2d9e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d9f0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
2da00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2da10 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  t..**.** ^The na
2da20 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  me of the collat
2da30 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73  ion is a UTF-8 s
2da40 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
2da50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2da60 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
2da70 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2da80 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
2da90 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2daa0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
2dab0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
2dac0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2dad0 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c  on16()..** ^Coll
2dae0 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74  ation names that
2daf0 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61   compare equal a
2db00 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c  ccording to [sql
2db10 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d  ite3_strnicmp()]
2db20 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
2db30 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d  ed to be the sam
2db40 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e name..**.** ^(
2db50 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2db60 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75  nt (eTextRep) mu
2db70 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65  st be one of the
2db80 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c   constants:.** <
2db90 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
2dba0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c  ITE_UTF8],.** <l
2dbb0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
2dbc0 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  LE],.** <li> [SQ
2dbd0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2dbe0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
2dbf0 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  TF16], or.** <li
2dc00 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  > [SQLITE_UTF16_
2dc10 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75  ALIGNED]..** </u
2dc20 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65  l>)^.** ^The eTe
2dc30 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64  xtRep argument d
2dc40 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e  etermines the en
2dc50 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67  coding of string
2dc60 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74  s passed.** to t
2dc70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2dc80 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20  ction callback, 
2dc90 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54  xCallback..** ^T
2dca0 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  he [SQLITE_UTF16
2dcb0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54  ] and [SQLITE_UT
2dcc0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
2dcd0 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70  ues for eTextRep
2dce0 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67  .** force string
2dcf0 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69  s to be UTF16 wi
2dd00 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  th native byte o
2dd10 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  rder..** ^The [S
2dd20 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2dd30 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65  NED] value for e
2dd40 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73  TextRep forces s
2dd50 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a  trings to begin.
2dd60 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79  ** on an even by
2dd70 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a  te address..**.*
2dd80 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72  * ^The fourth ar
2dd90 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73  gument, pArg, is
2dda0 20 61 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64   a application d
2ddb0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
2ddc0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
2ddd0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
2dde0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2ddf0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2de00 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
2de10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2de20 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
2de30 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
2de40 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
2de50 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
2de60 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
2de70 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
2de80 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
2de90 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
2dea0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
2deb0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
2dec0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
2ded0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
2dee0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
2def0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2df00 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2df10 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
2df20 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
2df30 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
2df40 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
2df50 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
2df60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
2df70 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
2df80 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
2df90 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
2dfa0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2dfb0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
2dfc0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
2dfd0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
2dfe0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
2dff0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e000 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
2e010 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
2e020 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
2e030 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
2e040 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
2e050 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
2e060 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
2e070 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2e080 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
2e090 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
2e0a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e0b0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
2e0c0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
2e0d0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
2e0e0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
2e0f0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2e100 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2e110 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
2e120 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2e130 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
2e140 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
2e150 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e160 75 73 74 20 61 6c 77 61 79 20 72 65 74 75 72 6e  ust alway return
2e170 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72   the same answer
2e180 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61  .** given the sa
2e190 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74  me inputs.  If t
2e1a0 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61  wo or more colla
2e1b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
2e1c0 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a  re registered.**
2e1d0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   to the same col
2e1e0 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69  lation name (usi
2e1f0 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  ng different eTe
2e200 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68  xtRep values) th
2e210 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67  en all.** must g
2e220 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e  ive an equivalen
2e230 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e  t answer when in
2e240 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76  voked with equiv
2e250 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a  alent strings..*
2e260 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * The collating 
2e270 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62  function must ob
2e280 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ey the following
2e290 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20   properties for 
2e2a0 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41  all.** strings A
2e2b0 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a  , B, and C:.**.*
2e2c0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49  * <ol>.** <li> I
2e2d0 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41  f A==B then B==A
2e2e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  ..** <li> If A==
2e2f0 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20  B and B==C then 
2e300 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  A==C..** <li> If
2e310 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67   A&lt;B THEN B&g
2e320 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  t;A..** <li> If 
2e330 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b  A&lt;B and B&lt;
2e340 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a  C then A&lt;C..*
2e350 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </ol>.**.** If
2e360 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   a collating fun
2e370 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20  ction fails any 
2e380 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e  of the above con
2e390 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61  straints and tha
2e3a0 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66  t.** collating f
2e3b0 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69  unction is  regi
2e3c0 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c  stered and used,
2e3d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2e3e0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
2e3f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2e400 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e410 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e420 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b  n_v2() works lik
2e430 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e440 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20  _collation().** 
2e450 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f  with the additio
2e460 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74  n that the xDest
2e470 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
2e480 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20  invoked on pArg 
2e490 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c  when.** the coll
2e4a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
2e4b0 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43  s deleted..** ^C
2e4c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e4d0 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77  ns are deleted w
2e4e0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
2e4f0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2e500 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  .** calls to the
2e510 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
2e520 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2e530 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61   when the.** [da
2e540 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e550 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69  n] is closed usi
2e560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2e570 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
2e580 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61   xDestroy callba
2e590 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e  ck is <u>not</u>
2e5a0 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a   called if the .
2e5b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
2e5c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2e5d0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e   function fails.
2e5e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2e5f0 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  hat invoke.** sq
2e600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e610 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68  lation_v2() with
2e620 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73   a non-NULL xDes
2e630 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68  troy argument sh
2e640 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74  ould .** check t
2e650 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61  he return code a
2e660 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  nd dispose of th
2e670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2e680 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  ta pointer.** th
2e690 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20  emselves rather 
2e6a0 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53  than expecting S
2e6b0 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69  QLite to deal wi
2e6c0 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a  th it for them..
2e6d0 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65  ** This is diffe
2e6e0 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20  rent from every 
2e6f0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
2e700 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63  erface.  The inc
2e710 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69  onsistency .** i
2e720 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75  s unfortunate bu
2e730 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e  t cannot be chan
2e740 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  ged without brea
2e750 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a  king backwards .
2e760 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2e770 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2e780 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
2e790 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2e7a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2e7b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2e7c0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2e7d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e7e0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2e7f0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2e800 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2e810 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
2e820 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
2e830 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2e840 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2e850 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2e860 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2e870 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2e880 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
2e890 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2e8a0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2e8b0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
2e8c0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
2e8d0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2e8e0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2e8f0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
2e900 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
2e910 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
2e920 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2e930 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
2e940 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
2e950 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
2e960 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2e970 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
2e980 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2e990 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e9a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e9b0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2e9c0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2e9d0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2e9e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
2e9f0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2ea00 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2ea10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2ea20 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2ea30 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2ea40 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2ea50 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2ea60 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2ea70 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2ea80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2ea90 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2eaa0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
2eab0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
2eac0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
2ead0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
2eae0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2eaf0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2eb00 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2eb10 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2eb20 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2eb30 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2eb40 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2eb50 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2eb60 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2eb70 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2eb80 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
2eb90 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2eba0 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
2ebb0 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
2ebc0 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2ebd0 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2ebe0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2ebf0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
2ec00 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
2ec10 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
2ec20 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
2ec30 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
2ec40 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
2ec50 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2ec60 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
2ec70 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
2ec80 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
2ec90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2eca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
2ecb0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
2ecc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2ecd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2ece0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
2ecf0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
2ed00 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2ed10 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
2ed20 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2ed30 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2ed40 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2ed50 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
2ed60 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2ed70 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2ed80 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
2ed90 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2eda0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
2edb0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2edc0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
2edd0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2ede0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2edf0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2ee00 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
2ee10 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2ee20 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2ee30 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2ee40 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2ee50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2ee60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ee70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2ee80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2ee90 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2eea0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2eeb0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
2eec0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2eed0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
2eee0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2eef0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2ef00 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2ef10 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2ef20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
2ef30 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2ef40 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2ef50 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2ef60 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2ef70 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2ef80 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2ef90 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2efa0 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2efb0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2efc0 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2efd0 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2efe0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2eff0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2f000 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2f010 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2f020 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2f030 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2f040 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2f050 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2f060 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2f070 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2f080 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2f090 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2f0a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2f0b0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2f0c0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2f0d0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2f0e0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2f0f0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2f100 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2f110 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2f120 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2f130 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2f140 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2f150 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2f160 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2f170 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2f180 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2f190 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2f1a0 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2f1b0 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2f1c0 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2f1d0 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2f1e0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2f1f0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2f200 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2f210 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2f220 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2f230 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2f240 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2f250 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2f260 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2f270 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2f280 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2f290 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2f2a0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2f2b0 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
2f2c0 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2f2d0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2f2e0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
2f2f0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2f300 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2f310 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
2f320 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2f330 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2f340 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2f350 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2f360 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
2f370 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
2f380 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2f390 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2f3a0 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
2f3b0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2f3c0 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2f3d0 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
2f3e0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2f3f0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2f400 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
2f410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2f420 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2f430 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2f440 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2f450 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2f460 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2f470 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2f480 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
2f490 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
2f4a0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
2f4b0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
2f4c0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
2f4d0 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
2f4e0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
2f4f0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
2f500 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
2f510 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
2f520 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
2f530 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
2f540 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
2f550 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
2f560 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
2f570 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
2f580 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
2f590 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
2f5a0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
2f5b0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
2f5c0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2f5d0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
2f5e0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
2f5f0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
2f600 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
2f610 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2f620 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
2f630 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
2f640 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
2f650 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
2f660 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
2f670 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
2f680 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
2f690 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
2f6a0 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
2f6b0 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
2f6c0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
2f6d0 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
2f6e0 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
2f6f0 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
2f700 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
2f710 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
2f720 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
2f730 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
2f740 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
2f750 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74  ragraphs..*/.int
2f760 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2f770 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f780 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2f790 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2f7a0 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2f7b0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
2f7c0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2f7d0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2f7e0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2f7f0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2f800 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2f810 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2f820 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2f830 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2f840 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2f850 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
2f860 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
2f870 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
2f880 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2f890 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
2f8a0 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
2f8b0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2f8c0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2f8d0 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2f8e0 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2f8f0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2f900 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2f910 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2f920 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2f930 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2f940 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2f950 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2f960 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2f970 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2f980 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2f990 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2f9a0 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2f9b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f9c0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2f9d0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2f9e0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2f9f0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2fa00 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2fa10 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2fa20 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2fa30 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2fa40 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2fa50 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2fa60 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2fa70 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2fa80 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2fa90 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2faa0 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2fab0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2fac0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
2fad0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2fae0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
2faf0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2fb00 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
2fb10 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
2fb20 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2fb30 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2fb40 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
2fb50 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
2fb60 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2fb70 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
2fb80 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
2fb90 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
2fba0 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2fbb0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
2fbc0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
2fbd0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
2fbe0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2fbf0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
2fc00 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
2fc10 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
2fc20 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2fc30 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
2fc40 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
2fc50 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
2fc60 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
2fc70 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
2fc80 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
2fc90 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
2fca0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2fcb0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2fcc0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
2fcd0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
2fce0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2fcf0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
2fd00 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2fd10 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
2fd20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
2fd30 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
2fd40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fd50 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
2fd60 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
2fd70 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2fd80 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
2fd90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2fda0 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2fdb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
2fdc0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2fdd0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2fde0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fdf0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2fe00 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2fe10 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2fe20 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
2fe30 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
2fe40 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
2fe50 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2fe60 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2fe70 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2fe80 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2fe90 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
2fea0 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2feb0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2fec0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2fed0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2fee0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2fef0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2ff00 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2ff10 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
2ff20 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2ff30 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2ff40 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
2ff50 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2ff60 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2ff70 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2ff80 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2ff90 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2ffa0 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2ffb0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2ffc0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2ffd0 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2ffe0 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
2fff0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
30000 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
30010 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
30020 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
30030 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
30040 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
30050 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
30060 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
30070 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
30080 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
30090 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
300a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
300b0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
300c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
300d0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
300e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
300f0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
30100 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
30110 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
30120 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
30130 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
30140 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
30150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
30160 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
30170 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
30180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30190 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
301a0 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
301b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
301c0 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
301d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
301e0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
301f0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
30200 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
30210 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30220 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
30230 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
30240 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
30250 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30260 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
30270 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
30280 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
30290 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
302a0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
302b0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
302c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
302d0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
302e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
302f0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
30300 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
30310 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
30320 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
30330 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30340 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
30350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30360 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
30370 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
30380 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
30390 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
303a0 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
303b0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
303c0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
303d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
303e0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
303f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
30400 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
30420 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
30430 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
30440 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
30450 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
30460 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
30470 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
30480 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
30490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
304a0 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
304b0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
304c0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
304d0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
304e0 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
304f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30500 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
30510 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
30520 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
30530 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
30540 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
30550 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
30560 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
30570 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
30590 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
305a0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
305b0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
305c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
305d0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
305e0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
305f0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
30600 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
30610 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
30620 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
30630 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
30640 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
30650 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
30660 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
30670 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
30680 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
30690 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
306a0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
306b0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
306c0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
306d0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
306e0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
306f0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
30700 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
30710 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
30720 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
30730 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
30740 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
30750 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
30760 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
30770 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
30780 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
30790 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
307a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
307b0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
307c0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
307d0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
307e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
307f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
30800 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
30810 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
30820 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
30830 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
30840 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
30850 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
30860 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
30870 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30880 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
30890 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
308a0 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
308b0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
308c0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
308d0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
308e0 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
308f0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
30900 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
30910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
30920 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
30930 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
30940 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
30950 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
30960 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
30970 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
30980 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
30990 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
309a0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
309b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
309c0 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
309d0 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
309e0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
309f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
30a00 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
30a10 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
30a20 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
30a30 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
30a40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
30a50 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
30a60 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
30a70 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
30a80 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
30a90 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
30aa0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
30ab0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
30ac0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
30ad0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
30ae0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
30af0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
30b00 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
30b10 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
30b20 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
30b30 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
30b40 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
30b50 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
30b60 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
30b70 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
30b80 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
30b90 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
30ba0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
30bb0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
30bc0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
30bd0 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
30be0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
30bf0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
30c00 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
30c10 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
30c20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
30c30 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
30c40 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
30c50 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
30c60 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
30c70 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
30c80 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
30c90 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
30ca0 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
30cb0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
30cc0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
30cd0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
30ce0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
30cf0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
30d00 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
30d10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
30d20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
30d30 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
30d40 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
30d50 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
30d60 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
30d70 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
30d80 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
30d90 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
30da0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
30db0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
30dc0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
30dd0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30de0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
30df0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
30e00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
30e10 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  osed..**.** See 
30e20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
30e30 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d  3_update_hook()]
30e40 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76   interface..*/.v
30e50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  oid *sqlite3_com
30e60 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  mit_hook(sqlite3
30e70 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  *, int(*)(void*)
30e80 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
30e90 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
30ea0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
30eb0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c  void(*)(void *),
30ec0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
30ed0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43  CAPI3REF: Data C
30ee0 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69  hange Notificati
30ef0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
30f00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30f10 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
30f20 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
30f30 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
30f40 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
30f50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30f60 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
30f70 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
30f80 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
30f90 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
30fa0 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
30fb0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
30fc0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e   deleted..** ^An
30fd0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
30fe0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
30ff0 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  l to this functi
31000 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  on.** for the sa
31010 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
31020 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
31030 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dden..**.** ^The
31040 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
31050 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
31060 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
31070 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
31080 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
31090 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
310a0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66  leted..** ^The f
310b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
310c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
310d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
310e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
310f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
31100 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54  te_hook()..** ^T
31110 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
31120 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
31130 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
31140 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
31150 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
31160 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
31170 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
31180 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
31190 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
311a0 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
311b0 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ked..** ^The thi
311c0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
311d0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
311e0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
311f0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
31200 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
31210 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
31220 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
31230 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20  ed row..** ^The 
31240 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70  final callback p
31250 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31260 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72  [rowid] of the r
31270 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  ow..** ^In the c
31280 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
31290 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
312a0 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
312b0 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
312c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ce..**.** ^(The 
312d0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
312e0 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
312f0 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
31300 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
31310 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
31320 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
31330 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
31340 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  )^.**.** ^In the
31350 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
31360 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64  ntation, the upd
31370 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e  ate hook.** is n
31380 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
31390 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73  duplication rows
313a0 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65 63   are deleted bec
313b0 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f  ause of an.** [O
313c0 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20  N CONFLICT | ON 
313d0 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45  CONFLICT REPLACE
313e0 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20  ] clause.  ^Nor 
313f0 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
31400 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
31410 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
31420 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
31430 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
31440 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
31450 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
31460 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
31470 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
31480 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
31490 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
314a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
314b0 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
314c0 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
314d0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
314e0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
314f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31500 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
31510 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
31520 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
31530 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
31540 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
31550 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
31560 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
31570 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
31580 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
31590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
315a0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
315b0 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
315c0 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
315d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
315e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
315f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
31600 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
31610 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
31620 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
31630 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
31640 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
31650 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  raph..**.** ^The
31660 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
31670 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
31680 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tion.** returns 
31690 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
316a0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
316b0 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20   call.** on the 
316c0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
316d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
316e0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
316f0 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44   first call on D
31700 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31710 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
31720 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64  mmit_hook()] and
31730 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   [sqlite3_rollba
31740 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e  ck_hook()].** in
31750 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69  terfaces..*/.voi
31760 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
31770 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
31780 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
31790 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
317a0 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
317b0 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
317c0 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
317d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
317e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
317f0 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
31800 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  Cache.** KEYWORD
31810 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
31820 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  }.**.** ^(This r
31830 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
31840 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 73  r disables the s
31850 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61  haring of the da
31860 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20  tabase cache.** 
31870 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61 20  and schema data 
31880 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77 65  structures betwe
31890 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
318a0 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63  nection | connec
318b0 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65  tions].** to the
318c0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
318d0 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  Sharing is enabl
318e0 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
318f0 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e  nt is true.** an
31900 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74 68  d disabled if th
31910 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61  e argument is fa
31920 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  lse.)^.**.** ^Ca
31930 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20 65  che sharing is e
31940 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62  nabled and disab
31950 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69 72  led for an entir
31960 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68  e process..** Th
31970 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
31980 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
31990 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
319a0 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
319b0 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
319c0 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
319d0 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
319e0 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
319f0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ately..**.** ^(T
31a00 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67  he cache sharing
31a10 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69   mode set by thi
31a20 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65  s interface effe
31a30 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  cts all subseque
31a40 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b  nt.** calls to [
31a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
31a60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
31a70 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  2()], and [sqlit
31a80 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
31a90 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61   Existing databa
31aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63  se connections c
31ab0 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20  ontinue use the 
31ac0 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20  sharing mode.** 
31ad0 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65  that was in effe
31ae0 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74  ct at the time t
31af0 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e  hey were opened.
31b00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
31b10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31b20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73  [SQLITE_OK] if s
31b30 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20  hared cache was 
31b40 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
31b50 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  led.** successfu
31b60 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20  lly.  An [error 
31b70 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
31b80 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a  d otherwise.)^.*
31b90 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61 63  *.** ^Shared cac
31ba0 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  he is disabled b
31bb0 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74  y default. But t
31bc0 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65  his might change
31bd0 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65   in.** future re
31be0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
31bf0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
31c00 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20  that care about 
31c10 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
31c20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73  setting should s
31c30 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79  et it explicitly
31c40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f  ..**.** See Also
31c50 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65  :  [SQLite Share
31c60 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f  d-Cache Mode].*/
31c70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
31c80 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
31c90 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
31ca0 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
31cb0 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
31cc0 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
31cd0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
31ce0 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
31cf0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
31d00 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
31d10 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
31d20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
31d30 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
31d40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
31d50 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
31d60 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
31d70 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
31d80 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
31d90 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
31da0 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
31db0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
31dc0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
31dd0 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
31de0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
31df0 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
31e00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
31e10 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
31e20 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
31e30 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
31e40 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
31e50 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
31e60 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
31e70 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
31e80 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
31e90 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
31ea0 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
31eb0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
31ec0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
31ed0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
31ee0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31ef0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
31f00 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
31f10 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
31f20 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
31f30 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
31f40 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
31f50 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61  imit64() interfa
31f60 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71  ce sets and/or q
31f70 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f  ueries the.** so
31f80 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  ft limit on the 
31f90 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
31fa0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
31fb0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
31fc0 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74  QLite..** ^SQLit
31fd0 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65  e strives to kee
31fe0 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74  p heap memory ut
31ff0 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20  ilization below 
32000 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a  the soft heap.**
32010 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69   limit by reduci
32020 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ng the number of
32030 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74   pages held in t
32040 68 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a  he page cache.**
32050 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   as heap memory 
32060 75 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65  usages approache
32070 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  s the limit..** 
32080 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c  ^The soft heap l
32090 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62  imit is "soft" b
320a0 65 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75  ecause even thou
320b0 67 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65  gh SQLite strive
320c0 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c  s to stay.** bel
320d0 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74  ow the limit, it
320e0 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65   will exceed the
320f0 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68   limit rather th
32100 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61  an generate.** a
32110 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
32120 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65   error.  In othe
32130 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66  r words, the sof
32140 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a  t heap limit .**
32150 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
32160 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  y..**.** ^The re
32170 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
32180 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
32190 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74  p_limit64() is t
321a0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68  he size of.** th
321b0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
321c0 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  t prior to the c
321d0 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20 61 72  all.  ^If the ar
321e0 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65 67 61  gument N is nega
321f0 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e 6f 20  tive.** then no 
32200 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65 20 74  change is made t
32210 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  o the soft heap 
32220 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c 20 74  limit.  Hence, t
32230 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 73 69  he current.** si
32240 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74 20 68  ze of the soft h
32250 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20 62 65  eap limit can be
32260 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 69   determined by i
32270 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
32280 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
32290 69 74 36 34 28 29 20 77 69 74 68 20 61 20 6e 65  it64() with a ne
322a0 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e 74 2e  gative argument.
322b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
322c0 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a 65 72  rgument N is zer
322d0 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66 74 20  o then the soft 
322e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 64 69  heap limit is di
322f0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  sabled..**.** ^(
32300 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
32310 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66 6f 72  mit is not enfor
32320 63 65 64 20 69 6e 20 74 68 65 20 63 75 72 72 65  ced in the curre
32330 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
32340 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72 20 6d  n.** if one or m
32350 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  ore of following
32360 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72 65 20   conditions are 
32370 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  true:.**.** <ul>
32380 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73 6f 66  .** <li> The sof
32390 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
323a0 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 20  set to zero..** 
323b0 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63 63 6f  <li> Memory acco
323c0 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61 62 6c  unting is disabl
323d0 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d 62 69  ed using a combi
323e0 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  nation of the.**
323f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32400 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
32410 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
32420 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69 6d 65  ,...) start-time
32430 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20   option and.**  
32440 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f      the [SQLITE_
32450 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
32460 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  S] compile-time 
32470 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  option..** <li> 
32480 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 70  An alternative p
32490 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
324a0 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70 65 63  entation is spec
324b0 69 66 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ifed using.**   
324c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66     [sqlite3_conf
324d0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
324e0 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e 2e 29 2e  IG_PCACHE],...).
324f0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 70 61 67  .** <li> The pag
32500 65 20 63 61 63 68 65 20 61 6c 6c 6f 63 61 74 65  e cache allocate
32510 73 20 66 72 6f 6d 20 69 74 73 20 6f 77 6e 20 6d  s from its own m
32520 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75 70 70 6c  emory pool suppl
32530 69 65 64 0a 2a 2a 20 20 20 20 20 20 62 79 20 5b  ied.**      by [
32540 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
32550 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
32560 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e 29 20 72  AGECACHE],...) r
32570 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  ather than.**   
32580 20 20 20 66 72 6f 6d 20 74 68 65 20 68 65 61 70     from the heap
32590 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ..** </ul>)^.**.
325a0 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74  ** Beginning wit
325b0 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  h SQLite version
325c0 20 33 2e 37 2e 33 2c 20 74 68 65 20 73 6f 66 74   3.7.3, the soft
325d0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65   heap limit is e
325e0 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65 67 61 72  nforced.** regar
325f0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
32600 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
32610 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
32620 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 2a 2a  Y_MANAGEMENT].**
32630 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
32640 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
32650 20 20 57 69 74 68 20 5b 53 51 4c 49 54 45 5f 45    With [SQLITE_E
32660 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
32670 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20 74 68 65  AGEMENT],.** the
32680 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
32690 20 69 73 20 65 6e 66 6f 72 63 65 64 20 6f 6e 20   is enforced on 
326a0 65 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  every memory all
326b0 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74 68 6f 75  ocation.  Withou
326c0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  t.** [SQLITE_ENA
326d0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
326e0 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73 6f 66 74  EMENT], the soft
326f0 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6f   heap limit is o
32700 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20  nly enforced.** 
32710 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 61  when memory is a
32720 6c 6c 6f 63 61 74 65 64 20 62 79 20 74 68 65 20  llocated by the 
32730 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 65 73  page cache.  Tes
32740 74 69 6e 67 20 73 75 67 67 65 73 74 73 20 74 68  ting suggests th
32750 61 74 20 62 65 63 61 75 73 65 0a 2a 2a 20 74 68  at because.** th
32760 65 20 70 61 67 65 20 63 61 63 68 65 20 69 73 20  e page cache is 
32770 74 68 65 20 70 72 65 64 6f 6d 69 6e 61 74 65 20  the predominate 
32780 6d 65 6d 6f 72 79 20 75 73 65 72 20 69 6e 20 53  memory user in S
32790 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a 2a 20 61  QLite, most.** a
327a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 6c 6c  pplications will
327b0 20 61 63 68 69 65 76 65 20 61 64 65 71 75 61 74   achieve adequat
327c0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
327d0 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 77 69  t enforcement wi
327e0 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20 75 73 65  thout.** the use
327f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   of [SQLITE_ENAB
32800 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
32810 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  MENT]..**.** The
32820 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75   circumstances u
32830 6e 64 65 72 20 77 68 69 63 68 20 53 51 4c 69 74  nder which SQLit
32840 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63 65 20 74  e will enforce t
32850 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
32860 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61 6e 67 65  it may.** change
32870 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
32880 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
32890 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
328a0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
328b0 61 70 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74  ap_limit64(sqlit
328c0 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a  e3_int64 N);../*
328d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
328e0 70 72 65 63 61 74 65 64 20 53 6f 66 74 20 48 65  precated Soft He
328f0 61 70 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61  ap Limit Interfa
32900 63 65 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ce.** DEPRECATED
32910 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
32920 20 64 65 70 72 65 63 61 74 65 64 20 76 65 72 73   deprecated vers
32930 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
32940 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
32950 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65  mit64()].** inte
32960 72 66 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75  rface.  This rou
32970 74 69 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64  tine is provided
32980 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
32990 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
329a0 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20   only.  All new 
329b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
329c0 75 6c 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b  uld use the.** [
329d0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
329e0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74  p_limit64()] int
329f0 65 72 66 61 63 65 20 72 61 74 68 65 72 20 74 68  erface rather th
32a00 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a  an this one..*/.
32a10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32a20 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  D void sqlite3_s
32a30 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
32a40 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt N);.../*.** C
32a50 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
32a60 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
32a70 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
32a80 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
32a90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32aa0 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
32ab0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
32ac0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
32ad0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
32ae0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
32af0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
32b00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
32b10 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
32b20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
32b30 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
32b40 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
32b50 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
32b60 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
32b70 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
32b80 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
32b90 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
32ba0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32bb0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
32bc0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32bd0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
32be0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
32bf0 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
32c00 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
32c10 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
32c20 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
32c30 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
32c40 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
32c50 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
32c60 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
32c70 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
32c80 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
32c90 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
32ca0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
32cb0 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
32cc0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
32cd0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
32ce0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
32cf0 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
32d00 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
32d10 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
32d20 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
32d30 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
32d40 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
32d50 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
32d60 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
32d70 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
32d80 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
32d90 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
32da0 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
32db0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
32dc0 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
32dd0 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
32de0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
32df0 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
32e00 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
32e10 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
32e20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
32e30 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
32e40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32e50 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
32e60 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
32e70 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
32e80 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
32e90 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
32ea0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
32eb0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
32ec0 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
32ed0 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
32ee0 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
32ef0 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
32f00 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
32f10 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
32f20 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
32f30 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
32f40 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32f50 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
32f60 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
32f70 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
32f80 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
32f90 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
32fa0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
32fb0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
32fc0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
32fd0 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
32fe0 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
32ff0 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
33000 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
33010 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
33020 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
33030 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
33040 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
33050 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
33060 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
33070 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
33080 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
33090 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
330a0 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
330b0 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
330c0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
330d0 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
330e0 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
330f0 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
33100 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
33110 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
33120 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
33130 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
33140 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
33150 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33160 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
33170 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
33180 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
33190 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
331a0 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
331b0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
331c0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
331d0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
331e0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
331f0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
33200 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
33210 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
33220 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
33230 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
33240 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
33250 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
33260 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
33270 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
33280 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
33290 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
332a0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
332b0 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
332c0 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
332d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
332e0 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
332f0 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
33300 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
33310 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
33320 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
33330 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
33340 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
33350 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
33360 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
33370 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
33380 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
33390 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
333a0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
333b0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
333c0 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
333d0 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
333e0 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
333f0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
33400 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
33410 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
33420 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
33430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
33440 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
33450 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
33460 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
33470 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
33480 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
33490 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
334a0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
334b0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
334c0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
334d0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
334e0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
334f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33500 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
33510 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
33520 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
33530 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
33540 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
33550 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
33560 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
33570 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
33580 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
33590 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
335a0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
335b0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
335c0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
335d0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
335e0 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
335f0 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
33600 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
33610 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
33620 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
33630 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
33640 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
33650 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33660 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
33670 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
33680 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
33690 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
336a0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
336b0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
336c0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
336d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
336e0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
336f0 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
33700 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
33710 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
33720 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
33730 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
33740 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
33750 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
33760 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
33770 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
33780 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
33790 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
337a0 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
337b0 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
337c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
337d0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
337e0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
337f0 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
33800 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
33810 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
33820 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
33830 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
33840 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
33850 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
33860 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
33870 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
33880 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
33890 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
338a0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
338b0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
338c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
338d0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
338e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
338f0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
33900 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
33910 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
33920 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
33930 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
33940 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
33950 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
33960 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
33970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
33980 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
33990 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
339a0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
339b0 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
339c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
339d0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
339e0 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
339f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
33a00 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
33a10 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
33a20 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
33a30 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
33a40 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
33a50 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
33a60 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
33a70 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
33a80 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
33a90 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
33aa0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
33ab0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
33ac0 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
33ad0 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
33ae0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
33af0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
33b00 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
33b10 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
33b20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33b30 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
33b40 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
33b50 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
33b60 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
33b70 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
33b80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
33b90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
33ba0 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
33bb0 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
33bc0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
33bd0 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
33be0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
33bf0 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
33c00 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
33c10 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
33c20 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
33c30 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
33c40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
33c50 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
33c60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33c70 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
33c80 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
33c90 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
33ca0 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
33cb0 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
33cc0 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
33cd0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
33ce0 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
33cf0 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
33d00 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
33d10 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
33d20 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
33d30 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
33d40 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
33d50 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
33d60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
33d70 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
33d80 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
33d90 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
33da0 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
33db0 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
33dc0 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
33dd0 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
33de0 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
33df0 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
33e00 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
33e10 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
33e20 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
33e30 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
33e40 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
33e50 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
33e60 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
33e70 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
33e80 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
33e90 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
33ea0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
33eb0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
33ec0 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
33ed0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
33ee0 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
33ef0 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69 63  ally Load Static
33f00 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74 65  ally Linked Exte
33f10 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
33f20 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  is interface cau
33f30 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50 6f  ses the xEntryPo
33f40 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 74  int() function t
33f50 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
33f60 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64 61  .** each new [da
33f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33f80 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61 74  n] that is creat
33f90 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68 65  ed.  The idea he
33fa0 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78 45  re is that.** xE
33fb0 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20 74  ntryPoint() is t
33fc0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 66  he entry point f
33fd0 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79 20  or a statically 
33fe0 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65 78  linked SQLite ex
33ff0 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  tension.** that 
34000 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61 74  is to be automat
34010 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69 6e  ically loaded in
34020 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61 62  to all new datab
34030 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ase connections.
34040 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74 68  .**.** ^(Even th
34050 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69 6f  ough the functio
34060 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f 77  n prototype show
34070 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f 69  s that xEntryPoi
34080 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e 6f  nt() takes.** no
34090 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 72   arguments and r
340a0 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51 4c  eturns void, SQL
340b0 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e 74  ite invokes xEnt
340c0 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20 74  ryPoint() with t
340d0 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hree.** argument
340e0 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61 6e  s and expects an
340f0 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  d integer result
34100 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e 61   as if the signa
34110 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20 65  ture of the.** e
34120 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72 65  ntry point where
34130 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
34140 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
34150 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  pre>.** &nbsp;  
34160 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  int xEntryPoint(
34170 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73 71  .** &nbsp;    sq
34180 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26 6e  lite3 *db,.** &n
34190 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63 68  bsp;    const ch
341a0 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a 2a  ar **pzErrMsg,.*
341b0 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
341c0 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
341d0 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a 70  _api_routines *p
341e0 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b 20  Thunk.** &nbsp; 
341f0 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   );.** </pre></b
34200 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
34210 2a 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72 79  ** If the xEntry
34220 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65 6e  Point routine en
34230 63 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72 6f  counters an erro
34240 72 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61 6b  r, it should mak
34250 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 70  e *pzErrMsg.** p
34260 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72 6f  oint to an appro
34270 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
34280 73 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20 66  sage (obtained f
34290 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
342a0 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64 20  intf()]).** and 
342b0 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f 70  return an approp
342c0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
342d0 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e 73  e].  ^SQLite ens
342e0 75 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72 72  ures that *pzErr
342f0 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20 62  Msg.** is NULL b
34300 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74 68  efore calling th
34310 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 2e  e xEntryPoint().
34320 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69    ^SQLite will i
34330 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  nvoke.** [sqlite
34340 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70 7a  3_free()] on *pz
34350 45 72 72 4d 73 67 20 61 66 74 65 72 20 78 45 6e  ErrMsg after xEn
34360 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75 72  tryPoint() retur
34370 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a 20  ns.  ^If any.** 
34380 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65  xEntryPoint() re
34390 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c 20  turns an error, 
343a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
343b0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
343c0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20  pen16()],.** or 
343d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
343e0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70 72  ()] call that pr
343f0 6f 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74 72  ovoked the xEntr
34400 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66 61  yPoint() will fa
34410 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  il..**.** ^Calli
34420 6e 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f  ng sqlite3_auto_
34430 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69 74  extension(X) wit
34440 68 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  h an entry point
34450 20 58 20 74 68 61 74 20 69 73 20 61 6c 72 65 61   X that is alrea
34460 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69 73  dy.** on the lis
34470 74 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20 65  t of automatic e
34480 78 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20 68  xtensions is a h
34490 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20 5e  armless no-op. ^
344a0 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  No entry point.*
344b0 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  * will be called
344c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
344d0 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61 73  for each databas
344e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
344f0 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  t is opened..**.
34500 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
34510 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
34520 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
34530 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
34540 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
34550 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
34560 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
34570 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
34580 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
34590 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
345a0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
345b0 65 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 61  e disables all a
345c0 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
345d0 6f 6e 73 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  ons previously.*
345e0 2a 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  * registered usi
345f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ng [sqlite3_auto
34600 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
34610 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
34620 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
34630 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
34640 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
34650 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
34660 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
34670 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
34680 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
34690 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
346a0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
346b0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
346c0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
346d0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
346e0 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
346f0 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
34700 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
34710 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
34720 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
34730 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
34740 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
34750 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
34760 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
34770 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
34780 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
34790 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
347a0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
347b0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
347c0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
347d0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
347e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
347f0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
34800 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
34810 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
34820 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
34830 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
34840 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34850 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34860 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
34870 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
34880 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
34890 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
348a0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
348b0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
348c0 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
348d0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
348e0 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
348f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
34900 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
34910 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
34920 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74  called a a "virt
34930 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
34940 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74  ", .** defines t
34950 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34960 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  n of a [virtual 
34970 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68  tables].  .** Th
34980 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
34990 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20  sists mostly of 
349a0 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
349b0 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41  module..**.** ^A
349c0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
349d0 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64  odule is created
349e0 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61   by filling in a
349f0 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69   persistent.** i
34a00 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
34a10 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61  structure and pa
34a20 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20  ssing a pointer 
34a30 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65  to that instance
34a40 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34a50 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
34a60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
34a70 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
34a80 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74  ..** ^The regist
34a90 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
34aa0 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
34ab0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
34ac0 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
34ad0 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
34ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34af0 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
34b00 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
34b10 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
34b20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
34b30 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
34b40 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
34b50 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
34b60 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
34b70 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
34b80 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
34b90 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
34ba0 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
34bb0 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
34bc0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
34bd0 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
34be0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
34bf0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
34c00 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
34c10 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
34c20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
34c30 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
34c40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
34c50 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
34c60 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
34c70 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
34c80 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
34c90 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
34ca0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
34cb0 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
34cc0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
34cd0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
34ce0 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
34cf0 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
34d00 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34d10 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
34d20 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
34d30 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
34d40 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
34d50 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
34d60 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
34d70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
34d80 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
34d90 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
34da0 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
34db0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
34dc0 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
34dd0 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
34de0 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
34df0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
34e00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
34e10 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
34e20 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
34e30 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
34e40 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
34e50 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
34e60 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
34e70 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
34e80 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
34e90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
34ea0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
34eb0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
34ec0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
34ed0 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
34ee0 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
34ef0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
34f00 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
34f10 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
34f20 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
34f30 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
34f40 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
34f50 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
34f60 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34f70 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
34f80 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
34f90 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34fa0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
34fb0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
34fc0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
34fd0 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
34fe0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
34ff0 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
35000 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
35010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35020 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
35030 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35040 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35050 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
35060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35070 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
35080 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
35090 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
350a0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
350b0 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
350c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
350d0 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
350e0 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
350f0 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
35100 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
35110 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
35120 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
35130 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
35140 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
35150 73 20 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a  s used as part.*
35160 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
35170 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61  l table] interfa
35180 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ce to.** pass in
35190 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
351a0 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
351b0 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78  eply from the [x
351c0 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65  BestIndex].** me
351d0 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75  thod of a [virtu
351e0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
351f0 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
35200 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
35210 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
35220 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
35230 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
35240 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
35250 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
35260 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
35270 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
35280 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43  ..**.** ^(The aC
35290 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
352a0 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
352b0 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
352c0 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
352d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
352e0 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
352f0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
35300 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20  .** where OP is 
35310 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20  =, &lt;, &lt;=, 
35320 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29  &gt;, or &gt;=.)
35330 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63 75  ^  ^(The particu
35340 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a  lar operator is.
35350 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f  ** stored in aCo
35360 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73  nstraint[].op us
35370 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ing one of the.*
35380 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  * [SQLITE_INDEX_
35390 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20  CONSTRAINT_EQ | 
353a0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
353b0 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d  STRAINT_ values]
353c0 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64  .)^.** ^(The ind
353d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
353e0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
353f0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
35400 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
35410 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
35420 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
35430 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
35440 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
35450 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
35460 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
35470 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
35480 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
35490 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
354a0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
354b0 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
354c0 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
354d0 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
354e0 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
354f0 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
35500 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
35510 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
35520 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
35530 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
35540 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
35550 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
35560 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
35570 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
35580 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
35590 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
355a0 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
355b0 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
355c0 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
355d0 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
355e0 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
355f0 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
35600 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
35610 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
35620 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
35630 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
35640 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
35650 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
35660 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
35670 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
35680 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
35690 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
356a0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
356b0 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
356c0 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
356d0 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
356e0 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
356f0 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
35700 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
35710 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
35720 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
35730 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
35740 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
35750 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
35760 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
35770 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
35780 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
35790 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
357a0 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
357b0 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
357c0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
357d0 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
357e0 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
357f0 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
35800 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
35810 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
35820 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
35830 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
35840 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
35850 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
35860 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
35870 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
35880 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
35890 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
358a0 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
358b0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
358c0 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
358d0 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
358e0 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
358f0 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
35900 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
35910 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
35920 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
35930 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
35940 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
35950 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
35960 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
35970 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
35980 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
35990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
359a0 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
359b0 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
359c0 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
359d0 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
359e0 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
359f0 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
35a00 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
35a10 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
35a20 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
35a30 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
35a40 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
35a50 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
35a60 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
35a70 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
35a80 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
35a90 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
35aa0 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
35ab0 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
35ac0 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
35ad0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
35ae0 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
35af0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
35b00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
35b10 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
35b20 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
35b30 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
35b40 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
35b50 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
35b60 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
35b70 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
35b80 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
35b90 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
35ba0 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
35bb0 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
35bc0 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
35bd0 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
35be0 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
35bf0 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
35c00 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
35c10 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
35c20 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
35c30 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
35c40 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
35c50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
35c60 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
35c70 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
35c80 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
35c90 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
35ca0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
35cb0 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
35cc0 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
35cd0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
35ce0 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
35cf0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
35d00 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
35d10 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
35d20 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
35d30 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
35d40 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
35d50 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
35d60 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
35d70 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
35d80 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
35d90 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
35da0 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
35db0 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
35dc0 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
35dd0 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
35de0 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
35df0 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
35e00 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
35e10 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
35e20 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
35e30 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
35e40 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
35e50 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
35e60 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
35e70 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
35e80 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
35e90 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
35ea0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
35eb0 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
35ec0 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
35ed0 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
35ee0 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
35ef0 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
35f00 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
35f10 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
35f20 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
35f30 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
35f40 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
35f50 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
35f60 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
35f70 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
35f80 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
35f90 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
35fa0 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
35fb0 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
35fc0 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
35fd0 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
35fe0 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
35ff0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
36000 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
36010 61 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20  able Constraint 
36020 4f 70 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a  Operator Codes.*
36030 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f  *.** These macro
36040 73 20 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c  s defined the al
36050 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72  lowed values for
36060 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
36070 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f  _index_info].aCo
36080 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69  nstraint[].op fi
36090 65 6c 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65  eld.  Each value
360a0 20 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61   represents.** a
360b0 6e 20 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20  n operator that 
360c0 69 73 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e  is part of a con
360d0 73 74 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20  straint term in 
360e0 74 68 65 20 77 48 45 52 45 20 63 6c 61 75 73 65  the wHERE clause
360f0 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74   of.** a query t
36100 68 61 74 20 75 73 65 73 20 61 20 5b 76 69 72 74  hat uses a [virt
36110 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23  ual table]..*/.#
36120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36130 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
36140 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
36150 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36160 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
36170 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36180 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
36190 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
361a0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
361b0 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
361c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
361d0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
361e0 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
361f0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
36200 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
36210 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
36220 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
36230 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
36240 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a  ementation.**.**
36250 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
36260 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67   are used to reg
36270 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
36280 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
36290 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64  e] name..** ^Mod
362a0 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
362b0 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
362c0 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
362d0 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
362e0 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20  able] using the 
362f0 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72  module and befor
36300 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65  e using a.** pre
36310 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61  existing [virtua
36320 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65  l table] for the
36330 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   module..**.** ^
36340 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  The module name 
36350 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e  is registered on
36360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
36380 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  fied.** by the f
36390 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
363a0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
363b0 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65  e module is give
363c0 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63  n by the .** sec
363d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
363e0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
363f0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
36400 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  r to.** the impl
36410 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
36420 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
36430 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65   module].   ^The
36440 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d   fourth.** param
36450 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
36460 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61  rary client data
36470 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
36480 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
36490 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72  ** into the [xCr
364a0 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
364b0 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
364c0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
364d0 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e  e module.** when
364e0 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74   a new virtual t
364f0 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67  able is be being
36500 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e   created or rein
36510 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  itialized..**.**
36520 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
36530 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
36540 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61   interface has a
36550 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
36560 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
36570 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
36580 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70  ructor for the p
36590 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51  ClientData.  ^SQ
365a0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76  Lite will.** inv
365b0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
365c0 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20  or function (if 
365d0 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  it is not NULL) 
365e0 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e  when SQLite.** n
365f0 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74  o longer needs t
36600 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70  he pClientData p
36610 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65  ointer.  ^The de
36620 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c  structor will al
36630 73 6f 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64  so.** be invoked
36640 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
36650 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36660 6f 64 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73  odule_v2() fails
36670 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
36680 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
36690 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
366a0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
366b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
366c0 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20  odule_v2() with 
366d0 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75  a NULL.** destru
366e0 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ctor..*/.int sql
366f0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
36700 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
36710 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36720 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
36730 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
36740 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
36750 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36760 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
36770 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
36780 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
36790 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
367a0 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
367b0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
367c0 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
367d0 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a  Data          /*
367e0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
367f0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
36800 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  t */.);.int sqli
36810 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36820 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
36830 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
36840 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
36850 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
36860 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
36870 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36880 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
36890 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
368a0 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
368b0 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
368c0 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
368d0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
368e0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
368f0 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20  ntData,         
36900 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
36910 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
36920 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78  ect */.  void(*x
36930 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20  Destroy)(void*) 
36940 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65      /* Module de
36950 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
36960 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  n */.);../*.** C
36970 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36980 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20   Table Instance 
36990 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
369a0 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
369b0 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69  .**.** Every [vi
369c0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
369d0 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le] implementati
369e0 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
369f0 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62  ss.** of this ob
36a00 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65  ject to describe
36a10 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e   a particular in
36a20 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65  stance.** of the
36a30 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
36a40 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73  .  Each subclass
36a50 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c   will.** be tail
36a60 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63  ored to the spec
36a70 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68  ific needs of th
36a80 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  e module impleme
36a90 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  ntation..** The 
36aa0 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20  purpose of this 
36ab0 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f  superclass is to
36ac0 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20   define certain 
36ad0 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a  fields that are.
36ae0 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  ** common to all
36af0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
36b00 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tations..**.** ^
36b10 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
36b20 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
36b30 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
36b40 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
36b50 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
36b60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
36b70 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45  mprintf()] to zE
36b80 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
36b90 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
36ba0 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
36bb0 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
36bc0 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
36bd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
36be0 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
36bf0 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
36c00 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
36c10 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65  g.  ^After the e
36c20 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
36c30 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20  is delivered up 
36c40 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70  to the client ap
36c50 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73  plication, the s
36c60 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75  tring will be au
36c70 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66  tomatically.** f
36c80 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  reed by sqlite3_
36c90 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a  free() and the z
36ca0 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c  ErrMsg field wil
36cb0 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a  l be zeroed..*/.
36cc0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
36cd0 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71  tab {.  const sq
36ce0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d  lite3_module *pM
36cf0 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d  odule;  /* The m
36d00 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76  odule for this v
36d10 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a  irtual table */.
36d20 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20    int nRef;     
36d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36d40 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55    /* NO LONGER U
36d50 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a  SED */.  char *z
36d60 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20  ErrMsg;         
36d70 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
36d80 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73  r message from s
36d90 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
36da0 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
36db0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
36dc0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
36dd0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
36de0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
36df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36e00 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
36e10 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a   Cursor Object.*
36e20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
36e30 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
36e40 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63  {virtual table c
36e50 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65  ursor}.**.** Eve
36e60 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
36e70 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
36e80 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
36e90 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
36ea0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72  ** following str
36eb0 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69  ucture to descri
36ec0 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20  be cursors that 
36ed0 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a  point into the.*
36ee0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
36ef0 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a  ] and are used.*
36f00 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67  * to loop throug
36f10 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  h the virtual ta
36f20 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72  ble.  Cursors ar
36f30 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
36f40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
36f50 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78  module.xOpen | x
36f60 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  Open] method of 
36f70 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61  the module and a
36f80 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  re destroyed.** 
36f90 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
36fa0 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20  module.xClose | 
36fb0 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20  xClose] method. 
36fc0 20 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65   Cursors are use
36fd0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69  d.** by the [xFi
36fe0 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20  lter], [xNext], 
36ff0 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e  [xEof], [xColumn
37000 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20  ], and [xRowid] 
37010 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68  methods.** of th
37020 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20  e module.  Each 
37030 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
37040 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e  ation will defin
37050 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  e.** the content
37060 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72   of a cursor str
37070 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69  ucture to suit i
37080 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a  ts own needs..**
37090 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c  .** This supercl
370a0 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72  ass exists in or
370b0 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69  der to define fi
370c0 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73  elds of the curs
370d0 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  or that.** are c
370e0 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70  ommon to all imp
370f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f  lementations..*/
37100 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
37110 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20  vtab_cursor {.  
37120 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37130 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72  tab;      /* Vir
37140 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68  tual table of th
37150 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f  is cursor */.  /
37160 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
37170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37180 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
37190 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
371a0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
371b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
371c0 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f  are The Schema O
371d0 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  f A Virtual Tabl
371e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43  e.**.** ^The [xC
371f0 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
37200 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
37210 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74   a.** [virtual t
37220 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c  able module] cal
37230 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  l this interface
37240 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74  .** to declare t
37250 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e  he format (the n
37260 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70  ames and datatyp
37270 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
37280 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72  s) of.** the vir
37290 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79  tual tables they
372a0 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69   implement..*/.i
372b0 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
372c0 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
372d0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
372e0 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
372f0 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
37300 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
37310 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
37320 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61  .** ^(Virtual ta
37330 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
37340 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
37350 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
37360 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
37370 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
37380 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
37390 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
373a0 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
373b0 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
373c0 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
373d0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
373e0 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
373f0 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
37400 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
37410 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
37420 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
37430 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
37440 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
37450 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
37460 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
37470 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
37480 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
37490 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
374a0 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
374b0 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
374c0 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e  on is created.)^
374d0 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74    ^The implement
374e0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
374f0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
37500 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
37510 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
37520 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
37530 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
37540 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
37550 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
37560 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
37570 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
37580 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
37590 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
375a0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
375b0 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74   by a [virtual t
375c0 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  able]..*/.int sq
375d0 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66  lite3_overload_f
375e0 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a  unction(sqlite3*
375f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
37600 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72  uncName, int nAr
37610 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69  g);../*.** The i
37620 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
37630 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
37640 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20  chanism defined 
37650 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a  above (back up.*
37660 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72  * to a comment r
37670 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61  emarkably simila
37680 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69  r to this one) i
37690 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
376a0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
376b0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
376c0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
376d0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
376e0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
376f0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
37700 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
37710 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
37720 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
37730 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
37740 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
37750 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
37760 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
37770 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
37780 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
37790 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
377a0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
377b0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
377c0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  ent..*/../*.** C
377d0 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c  API3REF: A Handl
377e0 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e To An Open BLO
377f0 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  B.** KEYWORDS: {
37800 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c  BLOB handle} {BL
37810 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a  OB handles}.**.*
37820 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
37830 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
37840 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
37850 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a  BLOB on which.**
37860 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
37870 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
37880 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20  l BLOB I/O] can 
37890 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  be performed..**
378a0 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69   ^Objects of thi
378b0 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74  s type are creat
378c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
378d0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61  lob_open()].** a
378e0 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  nd destroyed by 
378f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
37900 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ose()]..** ^The 
37910 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
37920 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
37930 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
37940 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63   interfaces.** c
37950 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
37960 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c  ad or write smal
37970 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66  l subsections of
37980 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54   the BLOB..** ^T
37990 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
379a0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
379b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
379c0 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
379d0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79   in bytes..*/.ty
379e0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
379f0 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65  ite3_blob sqlite
37a00 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_blob;../*.** C
37a10 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20  API3REF: Open A 
37a20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65  BLOB For Increme
37a30 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e  ntal I/O.**.** ^
37a40 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73  (This interfaces
37a50 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68   opens a [BLOB h
37a60 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20  andle | handle] 
37a70 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61  to the BLOB loca
37a80 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52  ted.** in row iR
37a90 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75  ow, column zColu
37aa0 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65  mn, table zTable
37ab0 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62   in database zDb
37ac0 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f  ;.** in other wo
37ad0 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c  rds, the same BL
37ae0 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65  OB that would be
37af0 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a   selected by:.**
37b00 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
37b10 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20   SELECT zColumn 
37b20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20  FROM zDb.zTable 
37b30 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20  WHERE [rowid] = 
37b40 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29  iRow;.** </pre>)
37b50 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
37b60 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
37b70 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
37b80 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  n the BLOB is op
37b90 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a  ened for read.**
37ba0 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73   and write acces
37bb0 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72  s. ^If it is zer
37bc0 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f  o, the BLOB is o
37bd0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61  pened for read a
37be0 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73  ccess..** ^It is
37bf0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
37c00 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74   open a column t
37c10 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  hat is part of a
37c20 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61  n index or prima
37c30 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77  ry .** key for w
37c40 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72  riting. ^If [for
37c50 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
37c60 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  ints] are enable
37c70 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74  d, it is .** not
37c80 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
37c90 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
37ca0 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68  is part of a [ch
37cb0 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69  ild key] for wri
37cc0 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  ting..**.** ^Not
37cd0 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  e that the datab
37ce0 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20  ase name is not 
37cf0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61  the filename tha
37d00 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  t contains.** th
37d10 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72  e database but r
37d20 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c  ather the symbol
37d30 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ic name of the d
37d40 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20  atabase that.** 
37d50 61 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68  appears after th
37d60 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65  e AS keyword whe
37d70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
37d80 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e  s connected usin
37d90 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e  g [ATTACH]..** ^
37da0 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  For the main dat
37db0 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20  abase file, the 
37dc0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
37dd0 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72   "main"..** ^For
37de0 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68   TEMP tables, th
37df0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
37e00 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a  is "temp"..**.**
37e10 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b   ^(On success, [
37e20 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
37e30 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e  turned and the n
37e40 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ew [BLOB handle]
37e50 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74   is written.** t
37e60 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72  o *ppBlob. Other
37e70 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
37e80 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
37e90 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20   and *ppBlob is 
37ea0 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e  set.** to be a n
37eb0 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a  ull pointer.)^.*
37ec0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
37ed0 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62   sets the [datab
37ee0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37ef0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
37f00 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73  essage.** access
37f10 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65  ible via [sqlite
37f20 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64  3_errcode()] and
37f30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
37f40 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a  ()] and related.
37f50 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e  ** functions. ^N
37f60 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70  ote that the *pp
37f70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73  Blob variable is
37f80 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69   always initiali
37f90 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20  zed in a.** way 
37fa0 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61  that makes it sa
37fb0 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71  fe to invoke [sq
37fc0 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
37fd0 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a  ()] on *ppBlob.*
37fe0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
37ff0 74 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  the success or f
38000 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72  ailure of this r
38010 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  outine..**.** ^(
38020 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20  If the row that 
38030 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f  a BLOB handle po
38040 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66  ints to is modif
38050 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50  ied by an.** [UP
38060 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c  DATE], [DELETE],
38070 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c   or by [ON CONFL
38080 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74  ICT] side-effect
38090 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c  s.** then the BL
380a0 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72  OB handle is mar
380b0 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22  ked as "expired"
380c0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75  ..** This is tru
380d0 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20  e if any column 
380e0 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68  of the row is ch
380f0 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f  anged, even a co
38100 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68  lumn.** other th
38110 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42  an the one the B
38120 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70  LOB handle is op
38130 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c  en on.)^.** ^Cal
38140 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
38150 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
38160 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
38170 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20  ite()] for.** a 
38180 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e  expired BLOB han
38190 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e  dle fail with an
381a0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20   return code of 
381b0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
381c0 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69  ** ^(Changes wri
381d0 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42  tten into a BLOB
381e0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c   prior to the BL
381f0 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20  OB expiring are 
38200 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  not.** rolled ba
38210 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61  ck by the expira
38220 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42  tion of the BLOB
38230 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20  .  Such changes 
38240 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a  will eventually.
38250 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65  ** commit if the
38260 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
38270 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
38280 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55  tion.)^.**.** ^U
38290 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
382a0 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
382b0 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72  terface to deter
382c0 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66  mine the size of
382d0 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62  .** the opened b
382e0 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20  lob.  ^The size 
382f0 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f  of a blob may no
38300 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  t be changed by 
38310 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
38320 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44  e.  Use the [UPD
38330 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  ATE] SQL command
38340 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73   to change the s
38350 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62  ize of a.** blob
38360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
38370 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
38380 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lob()] and [sqli
38390 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
383a0 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65  lob()] interface
383b0 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69  s.** and the bui
383c0 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d  lt-in [zeroblob]
383d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61   SQL function ca
383e0 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65  n be used, if de
383f0 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65  sired,.** to cre
38400 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65  ate an empty, ze
38410 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69  ro-filled blob i
38420 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20  n which to read 
38430 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a  or write using.*
38440 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  * this interface
38450 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ..**.** To avoid
38460 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b   a resource leak
38470 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c  , every open [BL
38480 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c  OB handle] shoul
38490 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  d eventually.** 
384a0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61  be released by a
384b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
384c0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
384d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
384e0 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c  blob_open(.  sql
384f0 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63  ite3*,.  const c
38500 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73  har *zDb,.  cons
38510 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a  t char *zTable,.
38520 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43    const char *zC
38530 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33  olumn,.  sqlite3
38540 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69  _int64 iRow,.  i
38550 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69  nt flags,.  sqli
38560 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f  te3_blob **ppBlo
38570 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b.);../*.** CAPI
38580 33 52 45 46 3a 20 4d 6f 76 65 20 61 20 42 4c 4f  3REF: Move a BLO
38590 42 20 48 61 6e 64 6c 65 20 74 6f 20 61 20 4e 65  B Handle to a Ne
385a0 77 20 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  w Row.**.** ^Thi
385b0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
385c0 65 64 20 74 6f 20 6d 6f 76 65 20 61 6e 20 65 78  ed to move an ex
385d0 69 73 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64  isting blob hand
385e0 6c 65 20 73 6f 20 74 68 61 74 20 69 74 20 70 6f  le so that it po
385f0 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 64 69 66  ints.** to a dif
38600 66 65 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  ferent row of th
38610 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
38620 74 61 62 6c 65 2e 20 5e 54 68 65 20 6e 65 77 20  table. ^The new 
38630 72 6f 77 20 69 73 20 69 64 65 6e 74 69 66 69 65  row is identifie
38640 64 0a 2a 2a 20 62 79 20 74 68 65 20 72 6f 77 69  d.** by the rowi
38650 64 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  d value passed a
38660 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
38670 75 6d 65 6e 74 2e 20 4f 6e 6c 79 20 74 68 65 20  ument. Only the 
38680 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20 63 68  row can be.** ch
38690 61 6e 67 65 64 2e 20 5e 54 68 65 20 64 61 74 61  anged. ^The data
386a0 62 61 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20  base, table and 
386b0 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68 69 63 68 20  column on which 
386c0 74 68 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20  the blob handle 
386d0 69 73 20 6f 70 65 6e 0a 2a 2a 20 72 65 6d 61 69  is open.** remai
386e0 6e 20 74 68 65 20 73 61 6d 65 2e 20 4d 6f 76 69  n the same. Movi
386f0 6e 67 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62  ng an existing b
38700 6c 6f 62 20 68 61 6e 64 6c 65 20 74 6f 20 61 20  lob handle to a 
38710 6e 65 77 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a  new row can be.*
38720 2a 20 66 61 73 74 65 72 20 74 68 61 6e 20 63 6c  * faster than cl
38730 6f 73 69 6e 67 20 74 68 65 20 65 78 69 73 74 69  osing the existi
38740 6e 67 20 68 61 6e 64 6c 65 20 61 6e 64 20 6f 70  ng handle and op
38750 65 6e 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 2e  ening a new one.
38760 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 6e 65 77  .**.** ^(The new
38770 20 72 6f 77 20 6d 75 73 74 20 6d 65 65 74 20 74   row must meet t
38780 68 65 20 73 61 6d 65 20 63 72 69 74 65 72 69 61  he same criteria
38790 20 61 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33   as for [sqlite3
387a0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a  _blob_open()] -.
387b0 2a 2a 20 69 74 20 6d 75 73 74 20 65 78 69 73 74  ** it must exist
387c0 20 61 6e 64 20 74 68 65 72 65 20 6d 75 73 74 20   and there must 
387d0 62 65 20 65 69 74 68 65 72 20 61 20 62 6c 6f 62  be either a blob
387e0 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65 20 73   or text value s
387f0 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20  tored in.** the 
38800 6e 6f 6d 69 6e 61 74 65 64 20 63 6f 6c 75 6d 6e  nominated column
38810 2e 29 5e 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .)^ ^If the new 
38820 72 6f 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65  row is not prese
38830 6e 74 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c  nt in the table,
38840 20 6f 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65   or if.** it doe
38850 73 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20  s not contain a 
38860 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c  blob or text val
38870 75 65 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65  ue, or if anothe
38880 72 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  r error occurs, 
38890 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72  an.** SQLite err
388a0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
388b0 6e 65 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62  ned and the blob
388c0 20 68 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69   handle is consi
388d0 64 65 72 65