/ Hex Artifact Content
Login

Artifact 8cae23448cb0ebe0990d305c32435c2dfb21f937:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8580: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8590: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
85a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
85b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
85c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
85d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
85e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
85f0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8600: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8610: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8620: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8630: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8640: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8650: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8660: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8670: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8680: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8690: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
86a0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
86b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
86c0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
86d0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
86e0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
86f0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8700: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8710: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8720: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8730: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8740: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8760: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8770: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8780: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8790: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
87a0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
87b0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
87c0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
87d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
87e0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
87f0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8800: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8810: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8820: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8830: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8840: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8850: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8860: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8870: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8890: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
88a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
88b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
88c0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
88d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
88e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
88f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
8900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
8910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
89b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
89c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
89d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
89e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
89f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8a00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8a10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8a20: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8a30: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8a40: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
8a50: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8a60: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a70: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a80: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8a90: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8aa0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8ab0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8ac0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8ae0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8b00: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8b10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8b20: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8b30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8b40: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8b50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8b60: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8b70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8b80: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
8b90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ba0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8bb0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8bc0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
8bd0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
8be0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8bf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8c00: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8c10: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8c20: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8c30: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8c40: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
8c50: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
8c60: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8c70: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8c80: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8c90: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8ca0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8cb0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8cc0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8cd0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8ce0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8cf0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8d00: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8d10: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8d20: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8d40: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
8d50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
8d60: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8d90: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8da0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8db0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8dc0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8dd0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8de0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8df0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8e00: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8e10: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8e20: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8e30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8e40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8e60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8e80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8ea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8eb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8ec0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8ed0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ee0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8ef0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
8f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8f10: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8f20: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8f30: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
8f40: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
8f50: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
8f60: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
8f70: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
8f80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8f90: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8fa0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
8fb0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
8fc0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
8fd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
8fe0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
8ff0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9000: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9010: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9020: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9030: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9040: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9060: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9070: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9080: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9090: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
90a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
90b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
90c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
90d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
90e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
90f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9100: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9110: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9120: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9130: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9140: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9150: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9160: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9170: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9180: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9190: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
91a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
91b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
91c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
91d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
91e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
91f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9200: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9210: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9220: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9230: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9240: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9250: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9260: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9280: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9290: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
92a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
92b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
92c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
92d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
92e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
92f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9300: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9320: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9330: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9340: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9350: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9360: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9370: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9380: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9390: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
93a0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
93b0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
93c0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
93d0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
93e0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
93f0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9400: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9410: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9420: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9430: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9440: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9450: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9460: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9470: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9480: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9490: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
94a0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
94b0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
94c0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
94d0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
94e0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
94f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9500: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9510: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9520: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9530: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9540: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9550: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9560: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9570: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9580: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9590: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
95a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
95b0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
95c0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
95d0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
95e0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
95f0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9610: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9620: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9630: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9640: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9650: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9660: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9680: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9690: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
96a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
96b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
96c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
96d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
96e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
96f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9700: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9710: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9720: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9730: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9740: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9750: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9760: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9770: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9780: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9790: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
97a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
97b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
97c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
97d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
97e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
97f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9800: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9810: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9820: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9830: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9840: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9850: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9860: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9870: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9880: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
98a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
98b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
98c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
98d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
98e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
98f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
9900: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
9910: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
9920: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
9930: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
9940: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
9950: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
9960: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
9970: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
9980: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
9990: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
99a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
99b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
99c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
99d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
99e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
99f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
9a00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
9a10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
9a20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
9a40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9a50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
9a60: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
9a70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9a80: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9aa0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9ab0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9ac0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9ad0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
9ae0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
9af0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9b00: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9b10: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9b20: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9b30: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9b40: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9b50: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9b60: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9b70: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9b80: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9b90: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9bb0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9bc0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9bd0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9be0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9bf0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9c00: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9c10: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9c20: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9c30: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9c40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9c50: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9c60: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9c70: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9c80: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9ca0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9cb0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9cc0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9ce0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9cf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9d00: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9d10: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9d20: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9d30: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9d40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9d50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9d60: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9d70: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9d80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9d90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9da0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9db0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9dc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9dd0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9de0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
9df0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9e00: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9e10: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9e20: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9e30: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9e40: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9e50: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9e60: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9e70: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9e80: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9e90: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9ea0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9eb0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9ec0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9ed0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ee0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9ef0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
9f00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9f10: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9f20: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9f30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9f40: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9f50: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9f60: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9f70: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9f80: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9f90: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9fa0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9fb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9fc0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9fd0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9fe0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9ff0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a000: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a010: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a020: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a030: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a040: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a050: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a060: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a070: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a080: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a090: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a0a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a0b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a0d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a0e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a0f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a100: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a110: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a120: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a130: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a140: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a150: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a160: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a170: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a180: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a190: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a1a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a1b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a1c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a1d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a1e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a1f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a200: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a210: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a220: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a230: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a240: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a250: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a260: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a270: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a290: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a2a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a2b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a2c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a2d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a2e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
a300: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
a310: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
a320: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
a330: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
a340: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
a350: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
a360: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
a370: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
a380: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a390: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
a3a0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a3b0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
a3c0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
a3d0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
a3e0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
a3f0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
a400: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
a410: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
a420: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
a430: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
a440: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a450: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
a460: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
a470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a480: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
a490: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
a4a0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
a4b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a4c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
a4d0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
a4e0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
a4f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
a500: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
a510: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
a520: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
a530: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
a540: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
a550: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a560: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
a570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
a580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a590: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
a5a0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
a5b0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
a5c0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
a5d0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
a5e0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
a5f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
a610: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
a620: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
a630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
a640: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a650: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
a660: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a690: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a6b0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
a6c0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
a6d0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
a6e0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
a6f0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
a700: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
a710: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
a720: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
a730: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
a740: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
a750: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
a760: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
a770: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
a780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
a790: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
a7a0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
a7b0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
a7c0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
a7d0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
a7f0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
a800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
a810: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
a820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a830: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
a840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a850: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
a860: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
a870: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
a880: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
a890: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a8a0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
a8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
a8c0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
a8d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
a8e0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
a8f0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
a900: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
a910: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
a920: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
a930: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
a940: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
a950: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
a960: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
a970: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
a980: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
a990: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
a9a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
a9b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
a9c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a9e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
a9f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
aa00: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
aa20: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
aa30: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
aa40: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
aa50: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
aa60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
aa70: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
aa80: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
aa90: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
aaa0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
aab0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
aac0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
aad0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
aae0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
aaf0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ab00: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ab10: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ab20: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ab30: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ab40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ab50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ab60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ab70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ab80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ab90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
abb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
abc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
abd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
abe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
abf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ac00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ac10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ac20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ac30: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ac40: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
ac50: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
ac60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ac70: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
ac80: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ac90: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
aca0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
acb0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
acc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
acd0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ace0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
acf0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ad00: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ad10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ad20: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ad30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ad40: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
ad50: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
ad60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ad70: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
ad80: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
ad90: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
ada0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
adb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
adc0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
add0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ade0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
adf0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ae00: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ae10: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ae20: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ae30: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ae40: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ae50: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ae60: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ae70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ae80: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ae90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
aea0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
aeb0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
aec0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
aed0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
aee0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
aef0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
af00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
af10: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
af20: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
af30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
af40: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
af50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
af60: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
af70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
af80: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
af90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
afa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afc0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
afd0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
afe0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
aff0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b000: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b010: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b020: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b030: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b040: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b050: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b060: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b070: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b080: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b090: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b0a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b0b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b0c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b0d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b0e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b0f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b100: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b110: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b120: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b130: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b140: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b150: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b160: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b170: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b190: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b1b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b1c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b1d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b1e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b1f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b200: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b210: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b220: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b230: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b240: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b260: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b270: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b280: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b290: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b2a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b2c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b2d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b2e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b300: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
b310: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
b320: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b330: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
b340: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
b350: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
b360: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
b370: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
b380: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
b390: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
b3a0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
b3b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
b3c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3d0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
b3e0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
b3f0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
b400: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
b410: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
b420: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
b430: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b440: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
b450: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
b460: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
b470: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
b480: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
b490: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
b4a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
b4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b4c0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
b4d0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
b4e0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
b4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
b500: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
b510: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
b520: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
b530: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
b540: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
b550: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
b560: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
b570: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
b580: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
b590: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
b5a0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
b5b0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
b5c0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
b5d0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
b5e0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
b5f0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
b600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
b610: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
b620: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
b630: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
b640: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
b650: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b660: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b670: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
b680: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
b690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b6a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b6b0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
b6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b6d0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
b6e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
b6f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
b700: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b710: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b720: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
b730: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
b740: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
b750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b760: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
b770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
b780: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
b790: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b7a0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
b7b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
b7c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
b7d0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b7e0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
b7f0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b800: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
b810: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
b820: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
b830: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
b840: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
b850: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
b860: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
b870: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
b880: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
b890: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
b8a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b8b0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
b8c0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
b8d0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
b8e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b8f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
b900: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
b910: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
b920: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b930: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
b940: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
b950: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
b960: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
b970: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
b980: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
b990: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
b9a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
b9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
b9c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
b9d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
b9e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
b9f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
ba00: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ba10: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
ba20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba30: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
ba40: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
ba50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ba60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ba70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ba80: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
ba90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
baa0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
bab0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
bac0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
bad0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
bae0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
baf0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
bb00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
bb10: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
bb20: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
bb30: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
bb40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
bb50: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
bb60: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
bb70: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
bb80: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
bb90: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
bba0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bbc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbd0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
bc00: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
bc10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
bc20: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
bc30: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
bc40: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
bc50: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
bc60: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
bc70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc80: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
bc90: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
bca0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
bcb0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
bcc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
bcd0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
bce0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
bcf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bd00: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
bd20: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
bd30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd40: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
bd50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
bd60: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
bd80: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
bd90: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
bda0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
bdb0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
bdc0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
bdd0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
bde0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
bdf0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
be00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
be20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
be30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
be40: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
be50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
be60: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
be70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
be80: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
be90: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
bea0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
beb0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
bec0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
bed0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
bee0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
bef0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bf00: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
bf10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
bf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
bf40: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
bf50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf60: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
bf70: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
bf80: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
bf90: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
bfa0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
bfb0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
bfc0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
bfd0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
bfe0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
bff0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c000: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c020: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c030: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c040: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c050: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c060: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c090: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c0a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c0c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c0d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c0e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c0f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c100: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c110: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c120: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c130: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c140: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c150: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c160: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c170: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c180: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c190: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c1a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c1b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c1c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c1d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c1e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c1f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c200: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c210: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c220: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c230: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c240: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c250: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c260: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c270: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c280: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c290: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c2a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c2c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c2d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c2e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c2f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c310: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c320: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c340: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c350: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c360: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c370: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c380: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
c390: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c3a0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
c3b0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
c3c0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
c3d0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
c3e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
c3f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
c400: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
c410: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
c420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c430: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
c440: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
c450: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c460: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c470: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c480: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c490: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c4a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c4c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c4d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c4e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c4f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c500: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c510: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c520: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c530: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
c540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c550: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
c560: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c570: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
c580: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
c5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
c5b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
c5c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c5d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
c5e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
c5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
c600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
c610: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
c620: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c630: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c640: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c670: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
c680: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
c690: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
c6a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
c6b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
c6c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
c6d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
c6e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c6f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
c700: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
c710: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
c720: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
c730: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
c740: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
c750: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
c760: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
c770: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
c780: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c790: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
c7a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
c7b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
c7c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
c7d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
c7e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c7f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
c800: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
c810: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c820: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c830: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
c840: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
c850: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
c860: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
c870: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
c880: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
c890: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
c8a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
c8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
c8c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
c8d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
c8e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
c8f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
c900: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
c910: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
c920: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
c930: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
c940: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
c950: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
c960: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c970: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
c980: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
c990: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c9a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
c9b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
c9c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
c9d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
c9e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
c9f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
ca00: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
ca10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ca20: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ca30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ca40: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ca50: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ca60: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ca70: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ca80: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
ca90: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
caa0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
cab0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
cac0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
cad0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
cae0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
caf0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
cb00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
cb10: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
cb20: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
cb30: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
cb40: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
cb50: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
cb60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
cb70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cb80: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
cb90: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
cba0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
cbb0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
cbc0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
cbd0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
cbe0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
cbf0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
cc00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
cc10: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
cc20: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
cc30: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
cc40: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cc50: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
cc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
cc70: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
cc80: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
cc90: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
cca0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
ccb0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
ccc0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
ccd0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
cce0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
ccf0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
cd00: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
cd10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
cd20: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
cd30: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
cd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
cd50: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
cd60: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
cd70: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
cd80: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cd90: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
cda0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
cdb0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
cdc0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
cdd0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
cde0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
cdf0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
ce00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ce10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
ce20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ce30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
ce40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
ce50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
ce60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
ce80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
ce90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cea0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ceb0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cec0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ced0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cee0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cef0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cf00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cf10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cf20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cf30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
cf40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
cf50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
cf60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
cf70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
cf80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
cf90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
cfa0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
cfb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
cfc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
cfd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
cfe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
cff0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d000: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d010: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d020: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d030: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d040: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d050: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d060: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d070: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d080: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d0a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d0b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d0c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d0d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d0e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d0f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d100: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d110: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d120: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d130: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d140: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d150: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d160: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d170: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d180: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d190: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d1a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d1b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d1c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d1d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d1e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d1f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d200: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d210: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d220: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d230: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d240: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d260: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d270: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d280: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d2a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d2b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d2c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d2d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d2e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d2f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
d300: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
d310: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
d320: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
d330: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
d340: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
d350: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
d360: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
d370: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
d380: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
d390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
d3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
d3b0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
d3c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
d3d0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
d3e0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
d3f0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
d400: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
d410: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
d420: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
d430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d440: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
d450: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
d460: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
d470: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d480: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d490: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
d4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
d4b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
d4c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
d4d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
d4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d500: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
d510: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d520: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d530: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d540: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d550: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d560: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d570: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d590: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d5a0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d5b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d5c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d5d0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d5e0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d5f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d600: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d610: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d620: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d630: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d640: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d650: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d660: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d670: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d680: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d6a0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d6b0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d6c0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d6d0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d6e0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d6f0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d700: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d710: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d720: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d730: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d740: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d750: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d760: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d770: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d780: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d790: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d7a0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
d7b0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d7c0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d7d0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d7e0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d7f0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d800: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d810: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d820: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d830: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d850: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d860: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d870: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d880: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d890: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d8a0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d8b0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
d8c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
d8d0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
d8e0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
d8f0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
d900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d910: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
d920: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d930: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d940: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
d950: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
d960: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d970: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d980: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d990: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d9a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d9b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d9c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d9d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
d9e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
d9f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
da00: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
da10: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
da20: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
da30: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da50: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
da60: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
da70: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
da80: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
da90: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
daa0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
dab0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
dac0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
dae0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
daf0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
db00: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
db10: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
db20: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
db30: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
db40: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
db50: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
db60: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
db70: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
db80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db90: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
dba0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
dbb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dbc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dbd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dbe0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dbf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
dc30: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
dc40: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
dc50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
dc60: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
dc70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
dc80: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
dc90: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
dca0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
dcb0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
dcc0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
dcd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dce0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
dcf0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dd00: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dd10: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dd20: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dd30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dd40: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dd50: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
dd60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
dd70: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
dd80: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
dd90: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
dda0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
ddb0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
ddc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
ddd0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
dde0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
ddf0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
de00: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
de10: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
de20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de30: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
de40: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
de50: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
de60: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
de70: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
de80: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
de90: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
dea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
deb0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
dec0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
ded0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
dee0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
def0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
df00: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
df10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
df20: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
df30: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
df40: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
df50: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df60: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
df70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
df80: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
df90: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
dfa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
dfb0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
dfc0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
dfd0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
dfe0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
dff0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e000: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e010: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e020: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e030: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e040: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e050: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e060: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e070: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e080: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e090: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e0a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e0b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e0c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e0d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e0e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e0f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e100: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e110: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e120: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e130: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e150: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e160: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e170: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e180: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e190: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e1a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e1b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e1c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e1d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e1e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e200: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e210: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e220: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e230: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e240: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e250: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e260: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e270: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e280: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e290: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e2a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e2b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e2d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e2e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e2f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e300: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e310: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e320: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
e330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
e340: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
e350: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
e360: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
e370: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e380: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
e390: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
e3a0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
e3b0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
e3c0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
e3d0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
e3e0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
e3f0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
e400: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e410: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
e420: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e430: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
e440: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
e450: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
e460: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
e470: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
e480: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
e490: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
e4a0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
e4b0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
e4c0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e4f0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
e500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
e510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
e520: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
e530: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
e540: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e550: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
e560: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e570: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
e580: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e590: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e5a0: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
e5b0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e5c0: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
e5d0: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
e5e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
e5f0: 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
e600: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
e610: 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
e620: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
e630: 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
e640: 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
e650: 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
e660: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
e670: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
e680: 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
e690: 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
e6a0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e6b0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
e6c0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
e6d0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
e6e0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
e6f0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
e700: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
e710: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
e720: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
e730: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
e740: 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
e750: 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
e760: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
e770: 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
e780: 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  rach allocations
e790: 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
e7a0: 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
e7b0: 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
e7c0: 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
e7d0: 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
e7e0: 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
e7f0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
e800: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
e810: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e820: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
e830: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e840: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
e860: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
e870: 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
e880: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
e890: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
e8a0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
e8b0: 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
e8c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
e8d0: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
e8e0: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
e8f0: 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
e900: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
e910: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
e920: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
e930: 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
e940: 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
e950: 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
e960: 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
e970: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
e980: 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
e990: 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
e9a0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
e9b0: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
e9c0: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e9d0: 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
e9e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
e9f0: 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
ea00: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
ea10: 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
ea20: 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
ea30: 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
ea40: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
ea50: 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
ea60: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ea70: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ea80: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ea90: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
eaa0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
eab0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
eac0: 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
ead0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
eae0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
eaf0: 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
eb00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
eb10: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
eb20: 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
eb30: 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
eb40: 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
eb50: 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
eb60: 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
eb70: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
eb80: 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
eb90: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
eba0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
ebb0: 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
ebc0: 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
ebd0: 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
ebe0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
ebf0: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
ec00: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
ec10: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
ec20: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
ec30: 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
ec40: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
ec50: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
ec60: 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
ec70: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
ec80: 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
ec90: 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
eca0: 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
ecb0: 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
ecc0: 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
ecd0: 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
ece0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
ecf0: 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
ed00: 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
ed10: 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
ed20: 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
ed30: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
ed40: 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
ed50: 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
ed60: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
ed70: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
ed80: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
ed90: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
eda0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
edb0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
edc0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
edd0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
ede0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
edf0: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
ee00: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
ee10: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
ee20: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
ee30: 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
ee40: 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
ee50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
ee60: 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
ee70: 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
ee80: 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
ee90: 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
eea0: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
eeb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
eec0: 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
eed0: 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
eee0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
eef0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ef00: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
ef10: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
ef20: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
ef30: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
ef40: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
ef50: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
ef60: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ef70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
ef80: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
ef90: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
efa0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
efb0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
efc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
efd0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
efe0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
eff0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f000: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
f010: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
f020: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
f030: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
f040: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
f050: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
f060: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
f070: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
f080: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
f090: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
f0a0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
f0b0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
f0c0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
f0d0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
f0e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
f0f0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
f100: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
f110: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
f120: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
f130: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
f140: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
f150: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
f160: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
f170: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
f180: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
f190: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
f1a0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
f1b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
f1c0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
f1d0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
f1e0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
f1f0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
f200: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
f210: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
f220: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
f230: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
f240: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
f250: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
f260: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
f270: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
f280: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
f290: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
f2a0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
f2b0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
f2c0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
f2d0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
f2e0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
f2f0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
f300: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
f310: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
f320: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
f330: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f340: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
f350: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f360: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f370: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f380: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f390: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
f3a0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
f3b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f3c0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
f3d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
f3e0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
f3f0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
f400: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
f410: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
f420: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
f430: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
f440: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
f450: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
f460: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
f470: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
f480: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f490: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
f4a0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
f4b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f4c0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
f4d0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
f4e0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
f4f0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
f500: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
f510: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
f520: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
f530: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
f540: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
f550: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
f560: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
f570: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
f580: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f590: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
f5a0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
f5b0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
f5c0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
f5d0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
f5e0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
f5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f600: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f610: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f620: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f630: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f640: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f650: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f660: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
f670: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
f680: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
f690: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
f6a0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f6b0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
f6c0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
f6d0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
f6e0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
f6f0: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
f700: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
f710: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
f720: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
f730: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
f740: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
f750: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
f760: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
f770: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
f780: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
f790: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
f7a0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
f7b0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
f7c0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
f7d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
f7e0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
f7f0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
f800: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
f810: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
f820: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
f830: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
f840: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
f850: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
f860: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f870: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
f880: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
f890: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
f8a0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
f8b0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
f8c0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
f8d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f8e0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
f8f0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f900: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
f910: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
f920: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
f930: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
f940: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
f950: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
f960: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
f970: 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
f980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
f990: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
f9a0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
f9b0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
f9c0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
f9d0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
f9e0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
f9f0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
fa00: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
fa10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fa20: 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
fa30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
fa40: 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
fa50: 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
fa60: 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
fa70: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
fa80: 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
fa90: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
faa0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
fab0: 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
fac0: 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
fad0: 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
fae0: 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
faf0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
fb00: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
fb10: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
fb20: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
fb30: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
fb40: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
fb50: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
fb60: 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
fb70: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
fb80: 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
fb90: 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
fba0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
fbb0: 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
fbc0: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
fbd0: 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
fbe0: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
fbf0: 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
fc00: 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
fc10: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
fc20: 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
fc30: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fc40: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
fc50: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
fc60: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
fc70: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
fc80: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
fc90: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
fca0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
fcb0: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
fcc0: 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
fcd0: 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
fce0: 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
fcf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
fd00: 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
fd10: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
fd20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fd30: 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _LOG</dt>.** <dd
fd40: 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
fd50: 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
fd60: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
fd70: 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
fd80: 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
fd90: 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
fda0: 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
fdb0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
fdc0: 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
fdd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
fde0: 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
fdf0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
fe00: 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
fe10: 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
fe20: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
fe30: 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
fe40: 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
fe50: 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
fe60: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
fe70: 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
fe80: 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
fe90: 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
fea0: 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
feb0: 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
fec0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
fed0: 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
fee0: 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
fef0: 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
ff00: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
ff10: 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
ff20: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
ff30: 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
ff40: 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
ff50: 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
ff60: 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
ff70: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ff80: 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
ff90: 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
ffa0: 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
ffb0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
ffc0: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
ffd0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
ffe0: 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
fff0: 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
10000 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
10010 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
10020 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
10030 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
10040 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
10050 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
10060 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
10070 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
10080 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
10090 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
100a0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
100b0 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
100c0 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
100d0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
100e0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
100f0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
10100 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
10110 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
10120 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
10130 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
10140 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
10150 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
10160 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
10170 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
10180 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
10190 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
101a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
101b0 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
101c0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
101d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
101e0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
101f0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
10210 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
10220 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
10230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
10240 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
10250 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
10260 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
10270 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10280 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
10290 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
102a0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
102b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
102c0 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
102d0 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
102e0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
102f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10300 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
10310 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
10320 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
10330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10340 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
10350 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
10360 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
10370 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
10380 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10390 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
103a0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
103b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
103c0 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
103d0 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
103e0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
103f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10400 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
10410 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
10420 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10430 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
10440 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
10450 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
10460 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
10470 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
10480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10490 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
104a0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
104b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
104c0 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
104d0 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  14  /* sqlite3_p
104e0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
104f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10500 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
10510 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69  E    15  /* sqli
10520 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
10530 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
10540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
10550 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
10560 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
10570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10580 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
10590 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
105a0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
105b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
105c0 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
105d0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
105e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105f0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
10600 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
10610 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10620 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
10630 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
10640 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
10650 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10660 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
10670 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
10680 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
10690 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
106a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
106b0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
106c0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
106d0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
106e0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
106f0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
10700 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10710 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
10720 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
10730 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
10740 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10750 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
10760 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
10770 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
10780 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
10790 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
107a0 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
107b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
107c0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
107d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
107e0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
107f0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
10800 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10810 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
10820 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
10830 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
10840 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
10850 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
10860 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
10870 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
10880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10890 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
108a0 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
108b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
108c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
108d0 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
108e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
108f0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
10900 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
10910 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
10920 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10930 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
10940 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
10950 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
10960 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
10970 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
10980 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
10990 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
109a0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
109b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
109c0 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
109d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
109e0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
109f0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
10a00 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
10a10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
10a20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
10a30 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
10a40 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
10a50 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
10a60 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
10a70 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
10a80 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
10a90 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
10aa0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
10ab0 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
10ac0 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
10ad0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
10ae0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
10af0 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
10b00 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
10b10 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
10b20 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
10b30 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
10b40 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
10b50 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
10b60 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
10b70 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
10b80 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
10b90 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
10ba0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
10bb0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
10bc0 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
10bd0 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
10be0 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
10bf0 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
10c00 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
10c10 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
10c20 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
10c30 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
10c40 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
10c50 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
10c60 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
10c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10c80 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
10c90 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
10ca0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
10cb0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
10cc0 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
10cd0 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
10ce0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
10cf0 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
10d00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10d10 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
10d20 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
10d30 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
10d40 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
10d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
10d60 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10d70 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
10d80 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f  * int int */.../
10d90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
10da0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
10db0 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
10dc0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
10dd0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
10de0 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
10df0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
10e00 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
10e10 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
10e20 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
10e30 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
10e40 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
10e50 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
10e60 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
10e70 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
10e80 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
10e90 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
10ea0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
10eb0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
10ec0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
10ed0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10ee0 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
10ef0 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
10f00 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
10f10 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
10f20 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
10f30 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
10f40 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57   called the [ROW
10f50 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e  ID | "rowid"]. ^
10f60 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77  The rowid is alw
10f70 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a  ays available.**
10f80 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65   as an undeclare
10f90 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52  d column named R
10fa0 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52  OWID, OID, or _R
10fb0 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73  OWID_ as long as
10fc0 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20   those.** names 
10fd0 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65  are not also use
10fe0 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20  d by explicitly 
10ff0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
11000 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62  . ^If.** the tab
11010 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20  le has a column 
11020 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52  of type [INTEGER
11030 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68   PRIMARY KEY] th
11040 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a  en that column.*
11050 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69  * is another ali
11060 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64  as for the rowid
11070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
11080 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
11090 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
110a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
110b0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
110c0 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74  RT] into the dat
110d0 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
110e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
110f0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
11100 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
11110 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
11120 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
11130 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
11140 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
11150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
11160 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
11170 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
11180 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
11190 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
111a0 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64   then the [rowid
111b0 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
111c0 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75  d.** row is retu
111d0 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
111e0 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20  tine as long as 
111f0 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72  the trigger is r
11200 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
11210 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
11220 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20  terminates, the 
11230 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11240 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  y this routine.*
11250 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65  * reverts to the
11260 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65   last value inse
11270 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  rted before the 
11280 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e  trigger fired.)^
11290 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45  .**.** ^An [INSE
112a0 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
112b0 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
112c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
112d0 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
112e0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
112f0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
11300 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
11310 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
11320 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49  outine.  ^Thus I
11330 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49  NSERT OR FAIL, I
11340 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c  NSERT OR IGNORE,
11350 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42   INSERT OR ROLLB
11360 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45  ACK,.** and INSE
11370 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65  RT OR ABORT make
11380 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74   no changes to t
11390 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
113a0 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  of this.** routi
113b0 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e  ne when their in
113c0 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  sertion fails.  
113d0 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52  ^(When INSERT OR
113e0 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
113f0 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
11400 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
11410 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
11420 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
11430 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
11440 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
11450 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
11460 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
11470 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
11480 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
11490 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
114a0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
114b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
114c0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
114d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  )^.**.** ^For th
114e0 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
114f0 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
11500 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
11510 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
11520 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
11530 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
11540 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
11550 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
11560 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69  ction is accessi
11570 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65  ble to SQL state
11580 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a  ments via the.**
11590 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f   [last_insert_ro
115a0 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69  wid() SQL functi
115b0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
115c0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
115d0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
115e0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
115f0 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  ame.** database 
11600 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
11610 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
11620 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
11630 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  )].** function i
11640 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68  s running and th
11650 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c  us changes the l
11660 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
11670 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  d],.** then the 
11680 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
11690 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
116a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
116b0 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61  is.** unpredicta
116c0 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f  ble and might no
116d0 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74  t equal either t
116e0 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65  he old or the ne
116f0 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74  w.** last insert
11700 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c   [rowid]..*/.sql
11710 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
11720 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
11730 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
11740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11750 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
11760 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11770 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11780 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11790 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
117a0 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
117b0 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
117c0 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
117d0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
117e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
117f0 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
11800 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
11810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11820 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
11830 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
11840 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
11850 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
11860 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
11870 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
11880 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
11890 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
118a0 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
118b0 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
118c0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
118d0 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
118e0 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
118f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
11900 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
11910 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
11920 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11930 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
11940 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
11950 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
11960 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
11970 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
11980 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
11990 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
119a0 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
119b0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
119c0 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
119d0 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
119e0 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
119f0 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
11a00 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
11a10 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
11a20 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
11a30 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
11a40 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
11a50 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
11a60 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
11a70 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
11a80 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
11a90 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
11aa0 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
11ab0 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
11ac0 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
11ad0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
11ae0 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
11af0 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
11b00 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
11b10 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
11b20 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
11b30 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
11b40 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
11b50 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
11b60 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
11b70 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
11b80 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
11b90 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
11ba0 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
11bb0 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
11bc0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
11bd0 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
11be0 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
11bf0 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
11c00 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
11c10 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
11c20 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
11c30 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
11c40 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
11c50 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
11c60 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
11c70 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
11c80 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
11c90 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
11ca0 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
11cb0 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
11cc0 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
11cd0 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
11ce0 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
11cf0 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
11d00 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
11d10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
11d20 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
11d30 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
11d40 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
11d50 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
11d60 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11d70 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
11d80 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
11d90 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
11da0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
11db0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
11dc0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
11dd0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
11de0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
11df0 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
11e00 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
11e10 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
11e20 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11e30 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
11e40 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
11e50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
11e60 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11e70 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
11e80 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
11e90 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
11ea0 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
11eb0 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
11ec0 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
11ed0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
11ee0 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
11ef0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
11f00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
11f10 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
11f20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
11f30 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
11f40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
11f50 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
11f60 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
11f70 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
11f80 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
11f90 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
11fa0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
11fb0 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
11fc0 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
11fd0 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
11fe0 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
11ff0 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
12000 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
12010 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
12020 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
12030 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
12040 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
12050 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
12060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
12070 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
12080 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
12090 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
120a0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
120b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
120c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
120d0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
120e0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
120f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
12100 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12110 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
12120 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12130 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
12140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12150 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
12160 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
12170 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
12180 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
12190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
121a0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
121b0 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20  by [INSERT],.** 
121c0 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
121d0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
121e0 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
121f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12200 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e  was opened..** ^
12210 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72  (The count retur
12220 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
12230 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69  otal_changes() i
12240 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e  ncludes all chan
12250 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20  ges.** from all 
12260 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
12270 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65  | trigger] conte
12280 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20  xts and changes 
12290 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65  made by.** [fore
122a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
122b0 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
122c0 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
122d0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
122e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
122f0 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
12300 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
12310 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
12320 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
12330 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
12340 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
12350 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
12360 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
12370 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
12380 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
12390 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
123a0 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
123b0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
123c0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
123d0 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
123e0 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
123f0 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68  ounted.)^.** ^Th
12400 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  e sqlite3_total_
12410 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
12420 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68  on counts the ch
12430 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73  anges as soon as
12440 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
12450 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
12460 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28  m is completed (
12470 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
12480 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20  nt handle.** is 
12490 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
124a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
124b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
124c0 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
124d0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
124e0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
124f0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
12500 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
12510 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
12520 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
12530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
12540 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
12550 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
12560 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
12570 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
12580 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
12590 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
125a0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
125b0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
125c0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
125d0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
125e0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
125f0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
12600 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12610 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
12630 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
12640 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
12650 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12660 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
12670 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
12680 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
12690 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
126a0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
126b0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
126c0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
126d0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
126e0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
126f0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
12700 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
12710 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
12720 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
12730 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
12740 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
12750 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
12760 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
12770 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
12780 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
12790 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
127a0 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
127b0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
127c0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
127d0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
127e0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
127f0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
12800 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
12810 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
12820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12830 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
12840 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
12850 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
12860 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12870 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
12880 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
12890 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
128a0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
128b0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
128c0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
128d0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
128e0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
128f0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12900 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
12910 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
12920 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
12930 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
12940 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
12950 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
12960 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
12970 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
12980 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
12990 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
129a0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
129b0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
129c0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
129d0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
129e0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
129f0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
12a00 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
12a10 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
12a20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
12a30 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
12a40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12a50 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
12a60 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
12a70 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
12a80 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
12a90 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
12aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12ab0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
12ac0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
12ad0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12ae0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12af0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
12b00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
12b10 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
12b20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
12b30 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
12b40 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
12b50 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
12b60 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
12b70 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
12b80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12b90 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
12ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
12bb0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
12bc0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
12bd0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
12be0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
12bf0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
12c00 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
12c10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12c20 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
12c30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12c40 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
12c50 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
12c60 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
12c70 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
12c80 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
12c90 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
12ca0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12cb0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12cc0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
12cd0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
12ce0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
12cf0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
12d00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
12d10 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
12d20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12d30 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
12d40 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
12d50 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
12d60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
12d70 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
12d80 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
12d90 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
12da0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
12db0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
12dc0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
12dd0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
12de0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
12df0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
12e00 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
12e10 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
12e20 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
12e30 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
12e40 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
12e50 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
12e60 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
12e70 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
12e80 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
12e90 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
12ea0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
12eb0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
12ec0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
12ed0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
12ee0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
12ef0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
12f00 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
12f10 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
12f20 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
12f30 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
12f40 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
12f50 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
12f60 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
12f70 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
12f80 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
12f90 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
12fa0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
12fb0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
12fc0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
12fd0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
12fe0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
12ff0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
13000 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
13010 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
13020 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
13030 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
13040 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
13050 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
13060 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
13070 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
13080 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
13090 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
130a0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
130b0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
130c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
130d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
130e0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
130f0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
13100 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
13110 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13120 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
13130 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
13140 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
13150 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
13160 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
13170 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
13180 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
13190 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
131a0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
131b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
131c0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
131d0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
131e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
131f0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
13200 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
13210 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13220 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
13230 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
13240 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
13250 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
13260 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
13270 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
13280 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
13290 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
132a0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
132b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
132c0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
132d0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
132e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
132f0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
13300 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
13310 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
13320 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
13330 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
13340 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13350 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
13360 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
13370 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
13380 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
13390 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
133a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
133b0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
133c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
133d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
133e0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
133f0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
13400 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13410 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
13420 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13430 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
13440 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
13450 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
13460 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
13470 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
13480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
13490 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
134a0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
134b0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
134c0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
134d0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
134e0 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
134f0 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
13500 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
13510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
13520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
13530 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
13540 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
13550 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
13560 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
13570 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
13580 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
13590 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
135a0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
135b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
135c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
135d0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
135e0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
135f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
13600 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13610 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
13620 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
13630 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
13640 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
13650 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
13660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
13670 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
13680 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13690 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
136a0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
136b0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
136c0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
136d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
136e0 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
136f0 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
13700 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13710 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
13720 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
13730 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
13740 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
13750 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
13760 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
13770 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
13780 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13790 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
137a0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
137b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
137c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
137d0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
137e0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
137f0 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
13800 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
13810 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
13820 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
13830 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
13840 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
13850 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
13860 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
13870 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
13880 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
13890 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
138a0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
138b0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
138c0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
138d0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
138e0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
138f0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
13900 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13910 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
13920 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13930 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
13940 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
13950 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
13960 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
13970 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
13980 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13990 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
139a0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
139b0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
139c0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
139d0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
139e0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
139f0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
13a00 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
13a10 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
13a20 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
13a30 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
13a40 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
13a50 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
13a60 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
13a70 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
13a80 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
13a90 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
13aa0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
13ab0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
13ac0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
13ad0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
13ae0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
13af0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
13b00 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
13b10 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
13b20 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
13b30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
13b40 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
13b50 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
13b60 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
13b70 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
13b80 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
13b90 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
13ba0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
13bb0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
13bc0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
13bd0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
13be0 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
13bf0 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
13c00 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
13c10 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
13c20 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13c30 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13c40 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13c50 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13c60 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13c70 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13c80 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13c90 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
13ca0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
13cb0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
13cc0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
13cd0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
13ce0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
13cf0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
13d00 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
13d10 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
13d20 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13d30 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13d40 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13d50 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13d60 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13d70 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13d80 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13d90 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
13da0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
13db0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
13dc0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
13dd0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
13de0 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
13df0 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
13e00 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
13e10 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
13e20 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
13e30 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
13e40 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
13e50 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
13e60 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13e70 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
13e80 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
13e90 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
13ea0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
13eb0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
13ec0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
13ed0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
13ee0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
13ef0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13f00 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
13f10 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13f20 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
13f30 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
13f40 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
13f50 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
13f60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
13f70 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f80 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f90 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
13fa0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
13fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
13fc0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
13fd0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
13fe0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
13ff0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
14000 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
14010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
14020 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
14030 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
14040 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
14050 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
14060 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
14070 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
14080 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
14090 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
140a0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
140b0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
140c0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
140d0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
140e0 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
140f0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
14100 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
14110 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
14120 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
14130 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
14140 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
14150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
14160 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
14170 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
14180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14190 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
141a0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
141b0 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
141c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
141d0 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
141e0 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  meout.**.** ^Thi
141f0 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
14200 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14210 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
14220 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
14230 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
14240 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
14250 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
14260 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
14270 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
14280 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
14290 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
142a0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
142b0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
142c0 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
142d0 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
142e0 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
142f0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
14300 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
14310 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
14320 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
14330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
14340 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
14350 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
14360 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14370 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  CKED]..**.** ^Ca
14380 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
14390 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
143a0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
143b0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
143c0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
143d0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
143e0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
143f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
14400 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
14410 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
14420 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14430 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79  nection] any any
14440 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
14450 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
14460 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
14470 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
14480 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
14490 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
144a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
144b0 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
144c0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
144d0 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
144e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
144f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
14500 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
14510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14520 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
14530 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
14540 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20  g Queries.**.** 
14550 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
14560 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
14570 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
14580 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
14590 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
145a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
145b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
145c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
145d0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
145e0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
145f0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
14600 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
14610 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
14620 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
14630 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
14640 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
14650 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
14660 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
14670 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14680 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
14690 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
146a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
146b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
146c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
146d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
146e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
146f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
14700 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
14710 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
14720 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
14730 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
14740 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
14750 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
14760 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
14770 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
14780 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
14790 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
147a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
147b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
147c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
147d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
147e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
147f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
14800 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
14810 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
14820 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
14830 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
14840 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
14850 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
14860 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
14870 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
14880 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
14890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
148a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
148b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
148c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
148d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
148e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
148f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
14900 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
14910 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
14920 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
14930 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
14940 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
14950 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
14960 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
14970 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
14980 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
14990 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
149a0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
149b0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
149c0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
149d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
149e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
149f0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
14a00 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
14a10 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
14a20 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
14a30 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
14a40 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
14a50 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
14a60 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
14a70 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
14a80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14a90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
14aa0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
14ab0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
14ac0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
14ad0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
14ae0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
14af0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
14b00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
14b10 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
14b20 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
14b30 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
14b40 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
14b50 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
14b60 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14b70 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
14b80 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
14b90 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
14ba0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
14bb0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
14bc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14bd0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
14be0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14bf0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
14c00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14c10 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
14c20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14c30 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
14c40 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
14c50 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
14c60 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
14c70 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14c80 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
14c90 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14ca0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e>.**.** ^The sq
14cb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14cc0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
14cd0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
14ce0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
14cf0 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
14d00 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
14d10 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
14d20 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
14d30 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
14d40 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
14d50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
14d60 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
14d70 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
14d80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
14d90 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
14da0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
14db0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
14dc0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
14dd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
14de0 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73  * it should pass
14df0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
14e00 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
14e10 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
14e20 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
14e30 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
14e40 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
14e50 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
14e60 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
14e70 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
14e80 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
14e90 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
14ea0 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
14eb0 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
14ec0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
14ed0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
14ee0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
14ef0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
14f00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
14f10 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
14f20 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
14f30 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
14f40 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
14f50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14f60 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
14f70 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
14f80 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
14f90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
14fa0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
14fb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
14fc0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
14fd0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
14fe0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
14ff0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
15000 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
15010 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
15020 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
15030 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
15040 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
15050 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
15060 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
15070 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
15080 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
15090 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
150a0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
150b0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
150c0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
150d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
150e0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
150f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
15100 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ].)^.*/.int sqli
15110 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
15120 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
15130 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
15140 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
15150 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
15160 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
15170 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
15180 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
15190 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
151a0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
151b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
151c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
151d0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
151e0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
151f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
15200 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
15210 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
15220 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
15230 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
15240 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
15250 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
15260 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
15270 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
15280 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
15290 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
152a0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
152b0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
152c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
152d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
152e0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
152f0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
15300 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
15310 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
15320 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
15330 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
15340 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
15350 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
15360 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
15370 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
15380 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
15390 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
153a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
153b0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
153c0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
153d0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
153e0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
153f0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
15400 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
15410 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
15420 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
15430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
15440 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15450 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
15460 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
15470 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
15480 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
15490 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  tring..**.** ^(I
154a0 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
154b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
154c0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
154d0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
154e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
154f0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
15500 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
15510 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
15520 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
15530 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15540 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
15550 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
15560 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15570 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
15580 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
15590 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
155a0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
155b0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
155c0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
155d0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
155e0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
155f0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15600 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15610 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15620 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
15630 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
15640 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15650 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
15660 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
15670 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
15680 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
15690 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
156a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
156b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
156c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
156d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
156e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
156f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
15700 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
15710 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
15720 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
15730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15740 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15750 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
15760 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
15770 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
15780 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
15790 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
157a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
157b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
157c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
157d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
157e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
157f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
15800 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
15810 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
15820 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
15830 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
15840 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
15850 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
15860 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
15870 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
15880 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
15890 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
158a0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
158b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
158c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
158d0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
158e0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
158f0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
15900 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
15910 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
15920 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
15930 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
15940 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
15950 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
15960 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
15970 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
15980 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
15990 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
159a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
159b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
159c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
159d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
159e0 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
159f0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
15a00 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
15a10 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
15a20 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
15a30 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
15a40 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
15a50 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
15a60 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
15a70 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
15a80 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
15a90 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
15aa0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
15ab0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
15ac0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
15ad0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
15ae0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
15af0 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
15b00 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
15b10 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
15b20 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
15b30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15b40 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15b50 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
15b60 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
15b70 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15b80 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
15b90 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
15ba0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
15bb0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
15bc0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15bd0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15be0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
15bf0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
15c00 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15c10 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
15c20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
15c30 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
15c40 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
15c50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
15c60 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
15c70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15c80 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
15c90 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
15ca0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
15cb0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
15cc0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
15cd0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
15ce0 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
15cf0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
15d00 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15d10 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
15d20 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
15d30 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
15d40 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
15d50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15d60 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
15d70 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
15d80 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
15d90 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
15da0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
15db0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
15dc0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15dd0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
15de0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
15df0 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
15e00 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
15e10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15e20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
15e30 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
15e40 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
15e50 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
15e60 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
15e70 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
15e80 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
15e90 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
15ea0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
15eb0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
15ec0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
15ed0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15ee0 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
15ef0 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
15f00 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
15f10 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
15f20 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
15f30 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
15f40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15f50 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
15f60 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
15f70 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
15f80 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
15f90 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
15fa0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
15fb0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
15fc0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
15fd0 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
15fe0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
15ff0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
16000 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
16010 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
16020 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
16030 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
16040 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
16050 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
16060 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
16070 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
16080 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16090 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
160a0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
160b0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
160c0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
160d0 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
160e0 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
160f0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
16100 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
16110 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
16120 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
16130 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
16140 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
16150 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
16160 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
16170 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
16180 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
16190 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
161a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
161b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
161c0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
161d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
161e0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
161f0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
16200 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16210 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
16220 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
16230 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
16240 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
16250 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
16260 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
16270 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
16280 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
16290 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
162a0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
162b0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
162c0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
162d0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
162e0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
162f0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
16300 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
16310 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
16320 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
16330 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
16340 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
16350 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
16360 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
16370 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
16380 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
16390 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
163a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
163b0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
163c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
163d0 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
163e0 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
163f0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
16400 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
16410 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
16420 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
16430 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16440 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16450 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16460 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16480 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
16490 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
164a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
164b0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
164c0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
164d0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
164e0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
164f0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
16500 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16510 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
16520 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
16530 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16540 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
16550 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16560 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
16570 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
16580 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
16590 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
165a0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
165b0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
165c0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
165d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
165e0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
165f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
16600 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
16610 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
16620 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
16630 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
16640 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
16650 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
16660 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
16670 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
16680 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
16690 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
166a0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
166b0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
166c0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
166d0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
166e0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
166f0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
16700 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
16710 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
16720 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
16730 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
16740 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
16750 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
16760 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
16770 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16780 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
16790 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
167a0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
167b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
167c0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
167d0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
167e0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
167f0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
16800 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
16810 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
16820 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
16830 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
16840 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
16850 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
16860 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
16870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
16880 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
16890 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
168a0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
168b0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
168c0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
168d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
168e0 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
168f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16900 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
16910 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
16920 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16930 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16940 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
16950 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
16960 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
16970 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
16980 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
16990 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
169a0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
169b0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
169c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
169d0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
169e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
169f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
16a00 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
16a10 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
16a20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
16a30 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
16a40 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
16a50 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
16a60 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
16a70 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
16a80 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16a90 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
16aa0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
16ab0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16ac0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
16ad0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
16ae0 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
16af0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
16b00 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
16b10 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
16b20 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
16b30 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
16b40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
16b50 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
16b60 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
16b70 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
16b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
16b90 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
16ba0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16bb0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
16bc0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
16bd0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
16be0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
16bf0 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a   boundary..**.**
16c00 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
16c10 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
16c20 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
16c30 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
16c40 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
16c50 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
16c60 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
16c70 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
16c80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
16c90 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
16ca0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
16cb0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
16cc0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
16cd0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
16ce0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
16cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
16d00 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
16d10 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
16d20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
16d30 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
16d40 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
16d50 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
16d60 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
16d70 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
16d80 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
16d90 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
16da0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
16db0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
16dc0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
16dd0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
16de0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
16df0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
16e00 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
16e10 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
16e20 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
16e30 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
16e40 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
16e50 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
16e60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
16e70 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
16e80 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
16e90 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
16ea0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
16eb0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
16ec0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16ed0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
16ee0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
16ef0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
16f00 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
16f10 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
16f20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
16f30 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
16f40 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
16f50 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
16f60 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
16f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
16f80 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
16f90 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
16fa0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
16fb0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
16fc0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
16fd0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
16fe0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
16ff0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17000 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
17010 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
17020 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
17030 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17040 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
17050 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
17060 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17070 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
17080 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
17090 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
170a0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
170b0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
170c0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
170d0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
170e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
170f0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
17100 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
17110 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17120 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
17130 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
17140 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
17150 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
17160 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
17170 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17180 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
17190 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
171a0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
171b0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
171c0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
171d0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
171e0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
171f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17200 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
17210 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
17220 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
17230 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
17240 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
17250 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
17260 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
17270 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
17280 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
17290 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
172a0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
172b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
172c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
172d0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
172e0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
172f0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
17300 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17310 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17320 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
17330 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
17340 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
17350 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
17360 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
17370 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
17380 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
17390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
173a0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
173b0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
173c0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
173d0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
173e0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
173f0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
17400 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
17410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
17420 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
17430 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
17440 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
17450 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
17460 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
17470 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
17480 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
17490 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
174a0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
174b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
174c0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
174d0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
174e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
174f0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
17500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17510 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
17520 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
17530 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
17540 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
17550 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
17560 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
17570 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
17580 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
17590 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
175a0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
175b0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
175c0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
175d0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
175e0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
175f0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
17600 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
17610 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
17620 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
17630 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
17640 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
17650 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
17660 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
17670 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
17680 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
17690 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
176a0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
176b0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
176c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
176d0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
176e0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
176f0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
17700 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
17710 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
17720 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
17730 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
17740 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
17750 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
17760 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
17770 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
17780 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
17790 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
177a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
177b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
177c0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
177d0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
177e0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
177f0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
17800 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
17810 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
17820 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
17830 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
17840 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
17850 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
17860 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
17870 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
17880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17890 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
178a0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
178b0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
178c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
178d0 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65  ters a authorize
178e0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
178f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
17900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
17910 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
17920 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
17930 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
17940 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17950 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
17960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17970 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
17980 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
17990 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
179a0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
179b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
179c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
179d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
179e0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
179f0 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74  re16_v2()].  ^At
17a00 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
17a10 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
17a20 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
17a30 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
17a40 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
17a50 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
17a60 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
17a70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17a80 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
17a90 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
17aa0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
17ab0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
17ac0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17ad0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
17ae0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
17af0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
17b00 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
17b10 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
17b20 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
17b30 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
17b40 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17b50 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
17b60 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
17b70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
17b80 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
17b90 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
17ba0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
17bb0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
17bc0 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
17bd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17be0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
17bf0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
17c00 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
17c10 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
17c20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
17c30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
17c40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17c50 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
17c60 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
17c70 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
17c80 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
17c90 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
17ca0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
17cb0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
17cc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17cd0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
17ce0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
17cf0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
17d00 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
17d10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
17d20 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
17d30 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
17d40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
17d50 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
17d60 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
17d70 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
17d80 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
17d90 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
17da0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
17db0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
17dc0 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
17dd0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17de0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17df0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
17e00 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
17e10 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
17e20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
17e30 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
17e40 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
17e50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17e60 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
17e70 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17e80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
17e90 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
17ea0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
17eb0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
17ec0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
17ed0 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
17ee0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
17ef0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
17f00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
17f10 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
17f20 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
17f30 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
17f40 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62  al.** details ab
17f50 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
17f60 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
17f70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
17f80 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
17f90 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
17fa0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
17fb0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
17fc0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
17fd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
17fe0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
17ff0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
18000 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
18010 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
18020 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
18030 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
18040 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
18050 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
18060 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
18070 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
18080 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18090 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
180a0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
180b0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
180c0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
180d0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
180e0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
180f0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
18100 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  ode is [SQLITE_D
18110 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63  ELETE] and the c
18120 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
18130 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ** [SQLITE_IGNOR
18140 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c  E] then the [DEL
18150 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70  ETE] operation p
18160 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a  roceeds but the.
18170 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  ** [truncate opt
18180 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69  imization] is di
18190 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72  sabled and all r
181a0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
181b0 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a  individually..**
181c0 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  .** An authorize
181d0 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b  r is used when [
181e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
181f0 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20  | preparing].** 
18200 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66  SQL statements f
18210 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64  rom an untrusted
18220 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75   source, to ensu
18230 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  re that the SQL 
18240 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f  statements.** do
18250 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65   not try to acce
18260 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65  ss data they are
18270 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20   not allowed to 
18280 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65  see, or that the
18290 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20  y do not.** try 
182a0 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63  to execute malic
182b0 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20  ious statements 
182c0 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20  that damage the 
182d0 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a  database.  For.*
182e0 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  * example, an ap
182f0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c  plication may al
18300 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e  low a user to en
18310 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a  ter arbitrary.**
18320 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72   SQL queries for
18330 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61   evaluation by a
18340 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20   database.  But 
18350 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
18360 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
18370 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20   the user to be 
18380 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62  able to make arb
18390 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74  itrary changes t
183a0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
183b0 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65  e.  An authorize
183c0 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20  r could then be 
183d0 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69  put in place whi
183e0 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65  le the.** user-e
183f0 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65  ntered SQL is be
18400 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
18410 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d  pare | prepared]
18420 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f   that.** disallo
18430 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78  ws everything ex
18440 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74  cept [SELECT] st
18450 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
18460 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
18470 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73  t need to proces
18480 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75  s SQL from untru
18490 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20  sted sources.** 
184a0 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69  might also consi
184b0 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73  der lowering res
184c0 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69  ource limits usi
184d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
184e0 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69  t()].** and limi
184f0 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69  ting database si
18500 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61  ze using the [ma
18510 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
18520 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64  RAGMA].** in add
18530 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61  ition to using a
18540 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  n authorizer..**
18550 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e  .** ^(Only a sin
18560 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
18570 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
18580 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
18590 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
185a0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
185b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
185c0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
185d0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
185e0 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44  ious call.)^  ^D
185f0 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
18600 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
18610 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
18620 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
18630 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
18640 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
18650 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  *.** The authori
18660 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  zer callback mus
18670 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
18680 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
18690 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
186a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
186b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61  at invoked the a
186c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
186d0 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ck..** Note that
186e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
186f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
18700 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
18710 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
18720 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
18730 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
18740 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
18750 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
18760 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  raph..**.** ^Whe
18770 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
18780 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64  re_v2()] is used
18790 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74   to prepare a st
187a0 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20  atement, the.** 
187b0 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20  statement might 
187c0 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64  be re-prepared d
187d0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
187e0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
187f0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
18800 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
18810 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
18820 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
18830 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
18840 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18850 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
18860 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
18870 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
18880 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
18890 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
188a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
188b0 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
188c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
188d0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
188e0 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
188f0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
18900 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
18910 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
18920 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
18930 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73  3_step()], unles
18940 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69  s.** as stated i
18950 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70  n the previous p
18960 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65  aragraph, sqlite
18970 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73  3_step() invokes
18980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70  .** sqlite3_prep
18990 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72  are_v2() to repr
189a0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
189b0 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61  t after a schema
189c0 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20   change..*/.int 
189d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
189e0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
189f0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
18a00 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
18a10 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
18a20 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18a30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
18a40 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
18a50 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
18a60 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
18a70 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
18a80 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
18a90 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
18aa0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18ab0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
18ac0 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
18ad0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
18ae0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
18af0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
18b00 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
18b10 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
18b20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
18b30 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
18b40 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
18b50 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18b60 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
18b70 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
18b80 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
18b90 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
18ba0 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
18bb0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
18bc0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
18bd0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
18be0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
18bf0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
18c00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
18c10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
18c20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
18c30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
18c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
18c50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
18c60 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
18c70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18c80 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
18c90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
18ca0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18cb0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
18cc0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
18cd0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
18ce0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
18cf0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
18d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18d10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
18d20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
18d30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
18d40 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
18d50 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
18d60 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
18d70 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
18d80 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** 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 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
18db0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
18dc0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
18dd0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
18de0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
18df0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
18e00 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
18e10 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
18e20 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
18e30 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
18e40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
18e50 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
18e60 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18e70 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
18e80 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
18e90 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
18ea0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
18eb0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
18ec0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
18ed0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18ee0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
18ef0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
18f00 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
18f10 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
18f20 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
18f30 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
18f40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18f50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
18f60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
18f70 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
18f80 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
18f90 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
18fa0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
18fb0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
18fc0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
18fd0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
18fe0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
18ff0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
19000 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
19010 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19020 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
19030 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
19040 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
19050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19060 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
19070 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
19080 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19090 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
190a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
190b0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
190c0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
190d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
190e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
190f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19100 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
19110 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
19120 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19130 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19140 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19150 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
19160 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
19170 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19180 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19190 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191a0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
191b0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
191c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
191d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
191e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
191f0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
19200 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
19210 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
19220 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19230 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19240 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
19250 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
19260 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19270 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19280 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19290 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
192a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
192b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
192c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
192d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
192e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
192f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19300 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19310 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19320 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
19330 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
19340 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19350 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
19360 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19370 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
19380 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
19390 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
193a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
193b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
193c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
193d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
193e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
193f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19400 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19410 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
19420 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
19430 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19440 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19450 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19460 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
19470 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
19480 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
19490 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
194c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
194d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
194e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
194f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19500 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
19510 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
19520 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19530 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19540 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19550 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
19560 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
19570 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19580 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
195a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
195b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
195c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
195d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
195e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
195f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
19600 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
19610 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
19620 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
19630 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
19640 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
19650 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
19660 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19670 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19680 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
19690 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
196a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
196b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
196c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
196d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
196e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
196f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
19700 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
19710 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19720 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
19730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19740 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
19750 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
19760 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19770 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
19780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
19790 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
197a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
197b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
197c0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
197d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
197e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
197f0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
19800 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19810 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
19820 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
19830 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
19840 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
19850 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19860 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
19870 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
19880 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19890 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198b0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
198c0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
198d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
198e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
198f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19900 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
19910 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
19920 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19930 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19940 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19950 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
19960 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
19970 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19980 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
19990 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199a0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
199b0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
199c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
199d0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
199e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
199f0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
19a00 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
19a10 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
19a20 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
19a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a40 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
19a50 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
19a60 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
19a70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19a80 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
19a90 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
19aa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
19ab0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
19ac0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
19ad0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
19ae0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
19af0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
19b00 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
19b10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
19b20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
19b30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19b40 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19b50 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
19b60 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
19b70 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
19b80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
19b90 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
19ba0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19bb0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
19bc0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
19bd0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
19be0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
19bf0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
19c00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
19c10 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
19c20 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
19c30 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
19c40 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
19c50 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
19c60 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
19c70 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
19c80 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
19c90 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
19ca0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
19cb0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
19cc0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
19cd0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
19ce0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
19cf0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
19d00 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19d10 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19d20 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
19d30 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
19d40 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
19d50 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
19d60 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
19d70 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
19d80 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
19d90 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
19da0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
19db0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
19dc0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
19dd0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
19de0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
19df0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
19e00 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
19e10 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
19e20 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
19e30 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
19e40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
19e50 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
19e60 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
19e70 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
19e80 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
19e90 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
19ea0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
19eb0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
19ec0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
19ed0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
19ee0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
19ef0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
19f00 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
19f10 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
19f20 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
19f30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
19f40 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
19f50 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
19f60 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
19f70 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
19f80 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
19f90 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
19fa0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
19fb0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
19fc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
19fd0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
19fe0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
19ff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1a000 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1a010 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1a020 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1a030 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1a040 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1a050 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1a060 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1a070 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
1a080 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67  s routine config
1a090 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ures a callback 
1a0a0 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a  function - the.*
1a0b0 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  * progress callb
1a0c0 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e  ack - that is in
1a0d0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1a0e0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a  ly during long.*
1a0f0 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  * running calls 
1a100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
1a110 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1a120 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ep()] and.** [sq
1a130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a140 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  )].  An example 
1a150 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
1a160 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
1a170 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
1a180 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
1a190 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
1a1a0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1a1b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a1c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1a1d0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1a1e0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1a1f0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1a200 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1a210 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1a220 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1a230 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1a240 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1a250 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a260 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1a270 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1a280 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1a290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a2a0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1a2b0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1a2c0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
1a2d0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1a2e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1a2f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1a300 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1a310 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1a320 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1a330 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1a340 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1a350 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
1a360 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1a370 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1a380 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1a390 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1a3a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a3b0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1a3c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1a3d0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1a3e0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1a3f0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1a400 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d  e file whose nam
1a410 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
1a420 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72  e.** filename ar
1a430 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
1a440 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1a450 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1a460 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1a470 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a480 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a490 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1a4a0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a4b0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1a4c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a4d0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
1a4e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1a4f0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1a500 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1a510 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1a520 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1a530 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1a540 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1a550 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1a560 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1a570 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1a580 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1a590 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1a5a0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1a5b0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1a5c0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1a5d0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1a5e0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
1a5f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a600 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
1a610 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
1a620 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
1a630 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1a640 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
1a650 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
1a660 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
1a670 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
1a680 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1a690 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1a6a0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1a6b0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1a6c0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1a6d0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1a6e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1a6f0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
1a700 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
1a710 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
1a720 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
1a730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a740 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
1a750 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
1a760 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
1a770 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a780 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1a790 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
1a7a0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
1a7b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
1a7c0 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
1a7d0 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
1a7e0 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
1a7f0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
1a800 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
1a810 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
1a820 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
1a830 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1a840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a850 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
1a860 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
1a870 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
1a880 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1a890 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
1a8a0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
1a8b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1a8c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
1a8d0 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
1a8e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1a8f0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
1a900 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
1a910 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
1a920 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
1a930 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
1a940 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
1a950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
1a960 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
1a970 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
1a980 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1a990 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1a9a0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1a9b0 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1a9c0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1a9d0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1a9e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a9f0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
1aa00 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
1aa10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1aa20 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e  REDCACHE],.** an
1aa30 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
1aa40 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1aa50 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1aa60 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1aa70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1aa80 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1aa90 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1aaa0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1aab0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1aac0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1aad0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1aae0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1aaf0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1ab00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1ab10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ab20 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1ab30 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1ab40 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1ab50 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1ab60 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1ab70 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1ab80 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1ab90 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1aba0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1abb0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1abc0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1abd0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1abe0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1abf0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1ac00 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1ac10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1ac20 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1ac30 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1ac40 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1ac50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1ac60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1ac70 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1ac80 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1ac90 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
1aca0 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
1acb0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
1acc0 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
1acd0 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
1ace0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
1acf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1ad00 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
1ad10 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
1ad20 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
1ad30 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
1ad40 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1ad50 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
1ad60 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
1ad70 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1ad80 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  e or one of the 
1ad90 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1ada0 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65  wn above combine
1adb0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  d.** with the [S
1adc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1add0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
1ade0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a  N_FULLMUTEX],.**
1adf0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1ae00 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f  AREDCACHE] and/o
1ae10 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1ae20 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1ae30 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  gs,.** then the 
1ae40 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
1ae50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
1ae60 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1ae70 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1ae80 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1ae90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aea0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1aeb0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1aec0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1aed0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1aee0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1aef0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1af00 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1af10 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1af20 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
1af30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1af40 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
1af50 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
1af60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1af70 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
1af80 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1af90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1afa0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
1afb0 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
1afc0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
1afd0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1afe0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
1aff0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
1b000 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
1b010 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1b020 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b030 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
1b040 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
1b050 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1b060 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
1b070 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
1b080 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
1b090 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
1b0a0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
1b0b0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1b0c0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
1b0d0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b0e0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1b0f0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1b100 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
1b110 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
1b120 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
1b130 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
1b140 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
1b150 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1b160 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1b170 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1b180 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1b190 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1b1a0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1b1b0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1b1c0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1b1d0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1b1e0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1b1f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1b200 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b210 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1b220 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1b230 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1b240 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1b250 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1b260 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1b270 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1b280 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1b290 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1b2a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1b2b0 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1b2c0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1b2d0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1b2e0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1b2f0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1b300 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1b310 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1b320 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1b330 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1b340 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1b350 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1b360 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1b370 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1b380 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1b390 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1b3a0 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1b3b0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1b3c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1b3d0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1b3e0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1b3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1b400 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  closed..**.** ^T
1b410 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b420 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1b430 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1b440 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1b450 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b460 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1b470 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1b480 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1b490 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1b4a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b4b0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1b4c0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1b4d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1b4e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1b4f0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1b500 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1b510 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1b520 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1b530 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1b540 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1b550 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1b560 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1b570 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1b580 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1b590 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1b5a0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1b5b0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1b5c0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1b5d0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1b5e0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1b5f0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1b600 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1b610 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1b620 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1b630 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1b640 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1b650 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1b660 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73  n_v2()..*/.int s
1b670 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
1b680 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1b690 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1b6a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1b6b0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1b6c0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1b6d0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1b6e0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1b6f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1b700 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1b710 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1b720 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1b730 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1b740 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1b750 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1b760 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1b770 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1b780 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
1b790 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
1b7a0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1b7b0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1b7c0 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
1b7d0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
1b7e0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1b7f0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
1b800 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
1b810 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
1b820 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b830 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
1b840 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
1b850 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
1b860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b870 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
1b880 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20   Messages.**.** 
1b890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1b8a0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1b8b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1b8c0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1b8d0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1b8e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1b8f0 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1b900 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1b910 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1b920 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1b930 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b940 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1b950 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1b960 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1b970 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1b980 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1b990 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b9a0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1b9b0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1b9c0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73  defined.  ^The s
1b9d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1b9e0 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74  errcode().** int
1b9f0 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61  erface is the sa
1ba00 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69  me except that i
1ba10 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
1ba20 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64   the .** [extend
1ba30 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1ba40 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64  even when extend
1ba50 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
1ba60 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  are.** disabled.
1ba70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ba80 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1ba90 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1baa0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1bab0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1bac0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1bad0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1bae0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1baf0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1bb00 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  vely..** ^(Memor
1bb10 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
1bb20 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
1bb30 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
1bb40 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65  ternally..** The
1bb50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1bb60 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f  s not need to wo
1bb70 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e  rry about freein
1bb80 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  g the result..**
1bb90 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72   However, the er
1bba0 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74  ror string might
1bbb0 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
1bbc0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  or deallocated b
1bbd0 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  y.** subsequent 
1bbe0 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53  calls to other S
1bbf0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20  QLite interface 
1bc00 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a  functions.)^.**.
1bc10 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1bc20 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1bc30 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1bc40 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1bc50 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1bc60 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1bc70 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1bc80 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1bc90 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1bca0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1bcb0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1bcc0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1bcd0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1bce0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1bcf0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1bd00 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1bd10 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1bd20 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1bd30 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1bd40 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1bd50 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1bd60 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1bd70 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1bd80 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1bd90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1bda0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1bdb0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1bdc0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1bdd0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1bde0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1bdf0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1be00 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1be10 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1be20 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1be30 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1be40 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1be50 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1be60 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1be70 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1be80 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1be90 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1bea0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1beb0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1bec0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1bed0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1bee0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1bef0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1bf00 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1bf10 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1bf20 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1bf30 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
1bf40 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1bf50 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
1bf60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1bf70 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1bf80 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
1bf90 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
1bfa0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
1bfb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
1bfc0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
1bfd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bfe0 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e  EF: SQL Statemen
1bff0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
1c000 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
1c010 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
1c020 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
1c030 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
1c040 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
1c050 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
1c060 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
1c070 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ent..** This obj
1c080 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79  ect is variously
1c090 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65   known as a "pre
1c0a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22  pared statement"
1c0b0 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c   or a.** "compil
1c0c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1c0d0 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61  " or simply as a
1c0e0 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a   "statement"..**
1c0f0 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20  .** The life of 
1c100 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  a statement obje
1c110 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e  ct goes somethin
1c120 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  g like this:.**.
1c130 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
1c140 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63  Create the objec
1c150 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1c160 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1c170 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20  r a related.**  
1c180 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a      function..**
1c190 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
1c1a0 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d  s to [host param
1c1b0 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65  eters] using the
1c1c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1c1d0 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66  ).**      interf
1c1e0 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75  aces..** <li> Ru
1c1f0 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c  n the SQL by cal
1c200 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ling [sqlite3_st
1c210 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72  ep()] one or mor
1c220 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
1c230 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65   Reset the state
1c240 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1c250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
1c260 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
1c270 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
1c280 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
1c290 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1c2a0 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
1c2b0 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1c2c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
1c2d0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1c2e0 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e  Refer to documen
1c2f0 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  tation on indivi
1c300 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f  dual methods abo
1c310 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ve for additiona
1c320 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1c330 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1c340 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
1c350 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
1c360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c370 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
1c380 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
1c390 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
1c3a0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
1c3b0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
1c3c0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
1c3d0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
1c3e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
1c3f0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
1c400 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1c410 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c420 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
1c430 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
1c440 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
1c450 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1c460 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
1c470 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
1c480 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
1c490 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
1c4a0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
1c4b0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
1c4c0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1c4d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
1c4e0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
1c4f0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
1c500 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1c510 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1c520 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1c530 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1c540 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
1c550 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
1c560 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
1c570 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
1c580 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1c590 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1c5a0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
1c5b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
1c5c0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
1c5d0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
1c5e0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
1c5f0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
1c600 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
1c610 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1c620 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1c630 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
1c640 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
1c650 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
1c660 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
1c670 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
1c680 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
1c690 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
1c6a0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
1c6b0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
1c6c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c6d0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
1c6e0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
1c6f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
1c700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1c710 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
1c720 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
1c730 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
1c740 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
1c750 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
1c760 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
1c770 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
1c780 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
1c790 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
1c7a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
1c7b0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
1c7c0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1c7d0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1c7e0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1c7f0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1c800 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1c810 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1c820 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1c830 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1c840 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1c850 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1c860 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1c870 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1c880 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1c890 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1c8a0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1c8b0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1c8c0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1c8d0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1c8e0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1c8f0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1c900 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1c910 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1c920 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1c930 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1c940 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1c950 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1c960 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1c970 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1c980 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1c990 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1c9a0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1c9b0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1c9c0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1c9d0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1c9e0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1c9f0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1ca00 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1ca10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1ca20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1ca30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1ca40 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1ca50 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1ca60 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1ca70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1ca80 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1ca90 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1caa0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1cab0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1cac0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1cad0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1cae0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1caf0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1cb00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1cb10 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
1cb20 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1cb30 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1cb40 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1cb50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1cb60 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1cb70 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
1cb80 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1cb90 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1cba0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1cbb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1cbc0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1cbd0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1cbe0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1cbf0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1cc00 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1cc10 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1cc20 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1cc30 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1cc40 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1cc50 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1cc60 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1cc70 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1cc80 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1cc90 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1cca0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1ccb0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1ccc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1ccd0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1cce0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1ccf0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1cd00 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1cd10 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
1cd20 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1cd30 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1cd40 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1cd50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1cd60 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1cd70 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
1cd80 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
1cd90 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cda0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1cdb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1cdc0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1cdd0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1cde0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1cdf0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1ce00 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
1ce10 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
1ce20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1ce30 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1ce40 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
1ce50 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
1ce60 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
1ce70 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1ce80 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1ce90 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
1cea0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
1ceb0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
1cec0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
1ced0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
1cee0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1cef0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1cf00 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1cf10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cf20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1cf30 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1cf40 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1cf50 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1cf60 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1cf70 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
1cf80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1cf90 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
1cfa0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
1cfb0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
1cfc0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
1cfd0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
1cfe0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
1cff0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
1d000 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
1d010 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
1d020 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
1d030 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
1d040 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
1d050 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
1d060 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1d070 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1d080 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1d090 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d0a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1d0b0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1d0c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1d0d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1d0e0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1d0f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d100 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
1d110 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
1d120 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
1d130 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d140 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1d150 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1d160 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d170 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1d180 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1d190 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1d1a0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1d1b0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
1d1c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d1d0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1d1e0 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
1d1f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d200 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
1d210 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
1d220 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1d230 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  ent.)^.**.** ^(<
1d240 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d250 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
1d260 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d270 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
1d280 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
1d290 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
1d2a0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1d2b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1d2c0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1d2d0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
1d2e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d2f0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
1d300 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
1d310 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d320 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
1d330 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
1d340 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d350 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
1d360 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
1d370 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d380 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1d390 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
1d3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1d3b0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
1d3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
1d3d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d3e0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1d3f0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
1d400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d410 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
1d420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d430 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
1d440 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1d450 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
1d460 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
1d470 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1d480 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
1d490 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
1d4a0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1d4b0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1d4c0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
1d4d0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1d4e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1d4f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
1d500 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
1d510 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
1d520 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
1d530 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
1d540 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
1d550 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
1d560 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
1d570 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
1d580 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
1d590 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d5a0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
1d5b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d5c0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
1d5d0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
1d5e0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1d5f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1d600 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1d610 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
1d620 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
1d630 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
1d640 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
1d650 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
1d660 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
1d670 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
1d680 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
1d690 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
1d6a0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
1d6b0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
1d6c0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
1d6d0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1d6e0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
1d6f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
1d700 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
1d710 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
1d720 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
1d730 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1d740 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
1d750 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
1d760 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1d770 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1d780 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1d790 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1d7a0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1d7b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
1d7c0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1d7d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1d7e0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1d7f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1d800 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1d810 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
1d820 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1d830 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
1d840 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
1d850 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
1d860 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
1d870 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
1d880 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
1d890 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
1d8a0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
1d8b0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
1d8c0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
1d8d0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
1d8e0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
1d8f0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
1d900 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
1d910 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
1d920 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
1d930 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
1d940 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
1d950 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
1d960 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1d970 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
1d980 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
1d990 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
1d9a0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
1d9b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
1d9c0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
1d9d0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
1d9e0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
1d9f0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
1da00 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
1da10 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1da20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1da30 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
1da40 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
1da50 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
1da60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
1da70 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
1da80 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
1da90 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
1daa0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
1dab0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
1dac0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
1dad0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
1dae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1daf0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
1db00 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
1db10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
1db20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
1db30 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
1db40 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
1db50 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
1db60 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1db70 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1db80 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1db90 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1dba0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1dbb0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1dbc0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
1dbd0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1dbe0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1dbf0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1dc00 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1dc10 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1dc20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1dc30 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1dc40 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1dc50 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
1dc60 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
1dc70 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
1dc80 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
1dc90 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
1dca0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1dcb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
1dcc0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
1dcd0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1dce0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
1dcf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dd00 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
1dd10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1dd20 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
1dd30 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
1dd40 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
1dd50 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
1dd60 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
1dd70 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
1dd80 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1dd90 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
1dda0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
1ddb0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
1ddc0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
1ddd0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
1dde0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
1ddf0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
1de00 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
1de10 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
1de20 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
1de30 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
1de40 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
1de50 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
1de60 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
1de70 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
1de80 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1de90 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
1dea0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
1deb0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
1dec0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
1ded0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
1dee0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
1def0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
1df00 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
1df10 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
1df20 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
1df30 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
1df40 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
1df50 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
1df60 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20  o run it again. 
1df70 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61 20   ^If the schema 
1df80 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1df90 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1dfa0 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1dfb0 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1dfc0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1dfd0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1dfe0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1dff0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1e000 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1e010 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
1e020 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
1e030 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1e040 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
1e050 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e060 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1e070 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1e080 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1e090 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1e0a0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1e0b0 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1e0c0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1e0d0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1e0e0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1e0f0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
1e100 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1e110 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
1e120 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
1e130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1e140 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
1e150 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
1e160 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
1e170 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
1e180 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
1e190 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
1e1a0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
1e1b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
1e1c0 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
1e1d0 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
1e1e0 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
1e1f0 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
1e200 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
1e210 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
1e220 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
1e230 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e240 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
1e250 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
1e260 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
1e270 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
1e280 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
1e290 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
1e2a0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
1e2b0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
1e2c0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
1e2d0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
1e2e0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1e2f0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
1e300 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72   of a [parameter
1e310 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1e320 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45 20  r] in the WHERE 
1e330 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20  clause might.** 
1e340 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72 79  change the query
1e350 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
1e360 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  ement, then the 
1e370 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65  statement may be
1e380 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1e390 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73  y recompiled (as
1e3a0 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65   if there had be
1e3b0 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  en a schema chan
1e3c0 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge) on the first
1e3d0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
1e3e0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1e3f0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20  wing any change 
1e400 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  to the .** [sqli
1e410 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
1e420 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65  bindings] of the
1e430 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1e440 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e  * </li>.** </ol>
1e450 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e460 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1e470 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1e480 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1e490 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e4a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1e4b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1e4c0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1e4d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1e4e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1e4f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1e500 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1e510 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1e520 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1e530 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1e540 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1e550 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1e560 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1e570 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1e580 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1e590 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e5a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1e5b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e5c0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e5d0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e5e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1e5f0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e600 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1e610 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1e620 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1e630 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1e640 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1e650 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1e660 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1e670 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1e680 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1e690 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1e6a0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1e6b0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1e6c0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1e6d0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1e6e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1e6f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1e700 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e710 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e720 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e730 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e740 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e750 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1e760 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1e770 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1e780 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e790 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1e7a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1e7b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e7c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e7d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e7e0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1e7f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e800 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e810 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1e830 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1e840 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1e850 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1e860 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1e870 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1e880 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1e890 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1e8a0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e8b0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e8c0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e8d0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e8e0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e8f0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e900 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e910 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e920 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1e930 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e940 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e950 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e960 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1e970 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
1e980 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
1e990 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
1e9a0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1e9b0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1e9c0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1e9d0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1e9e0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1e9f0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1ea00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ea10 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1ea20 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1ea30 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1ea40 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1ea50 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1ea60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ea70 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  2()]..*/.const c
1ea80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
1ea90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
1eaa0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
1eab0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
1eac0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
1ead0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1eae0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1eaf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1eb00 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1eb10 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1eb20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1eb30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1eb40 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1eb50 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1eb60 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1eb70 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1eb80 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1eb90 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1eba0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1ebb0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1ebc0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20   ^Values stored 
1ebd0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1ebe0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1ebf0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1ec00 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1ec10 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1ec20 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1ec30 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1ec40 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1ec50 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1ec60 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1ec70 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1ec80 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1ec90 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1eca0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1ecb0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1ecc0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1ecd0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1ece0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1ecf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1ed00 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1ed10 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1ed20 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1ed30 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1ed40 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1ed50 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1ed60 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1ed70 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1ed80 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1ed90 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1eda0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1edb0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1edc0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1edd0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1ede0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1edf0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1ee00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ee10 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1ee20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1ee30 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1ee40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ee50 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1ee60 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1ee70 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1ee80 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1ee90 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1eea0 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
1eeb0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1eec0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
1eed0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
1eee0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
1eef0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
1ef00 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
1ef10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
1ef20 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
1ef30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1ef40 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
1ef50 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
1ef60 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
1ef70 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1ef80 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1ef90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1efa0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
1efb0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
1efc0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
1efd0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
1efe0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
1eff0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
1f000 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
1f010 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
1f020 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
1f030 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1f040 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1f050 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1f060 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1f070 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
1f080 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
1f090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f0a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f0b0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
1f0c0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
1f0d0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
1f0e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
1f0f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1f100 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1f110 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
1f120 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f130 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1f140 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1f150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1f160 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1f170 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1f180 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f190 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1f1a0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1f1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1f1c0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1f1d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1f1e0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1f1f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1f200 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1f210 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1f220 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1f230 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1f240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1f250 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1f260 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1f270 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1f280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f290 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1f2a0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
1f2b0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
1f2c0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
1f2d0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
1f2e0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
1f2f0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
1f300 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
1f310 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
1f320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1f330 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
1f340 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
1f350 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
1f360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1f370 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
1f380 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
1f390 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1f3a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
1f3b0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
1f3c0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
1f3d0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
1f3e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
1f3f0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
1f400 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
1f410 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
1f420 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
1f430 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
1f440 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f450 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
1f460 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
1f470 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
1f480 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
1f490 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
1f4a0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
1f4b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
1f4c0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
1f4d0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
1f4e0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
1f4f0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
1f500 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
1f510 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
1f520 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
1f530 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
1f540 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
1f550 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
1f560 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
1f570 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
1f580 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
1f590 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing}.**.** ^(In 
1f5a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1f5b0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
1f5c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f5d0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
1f5e0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
1f5f0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
1f600 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
1f610 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
1f620 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
1f630 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
1f640 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
1f650 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
1f660 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
1f670 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
1f680 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
1f690 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
1f6a0 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
1f6b0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
1f6c0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
1f6d0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1f6e0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
1f6f0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
1f700 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
1f710 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1f720 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1f730 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1f740 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1f750 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1f760 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1f770 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1f780 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f790 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1f7a0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1f7b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1f7c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1f7d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f7e0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1f7f0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1f800 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1f810 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1f820 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1f830 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f840 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1f850 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
1f860 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1f870 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1f880 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1f890 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
1f8a0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1f8b0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1f8c0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
1f8d0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1f8e0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1f8f0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1f900 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1f910 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1f920 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1f930 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1f940 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1f950 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1f960 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
1f970 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1f980 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1f990 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1f9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f9b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1f9c0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1f9d0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
1f9e0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1f9f0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1fa00 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
1fa10 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1fa20 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1fa30 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1fa40 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1fa50 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1fa60 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1fa70 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1fa80 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1fa90 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
1faa0 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1fab0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1fac0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1fad0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
1fae0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1faf0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1fb00 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1fb10 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1fb20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1fb30 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1fb40 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1fb50 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1fb60 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1fb70 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1fb80 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1fb90 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
1fba0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
1fbb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1fbc0 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1fbd0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1fbe0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1fbf0 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1fc00 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1fc10 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1fc20 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
1fc30 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1fc40 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1fc50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1fc60 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1fc70 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1fc80 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1fc90 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1fca0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1fcb0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1fcc0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1fcd0 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20  ed with it. ^If 
1fce0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1fcf0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1fd00 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1fd10 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1fd20 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1fd30 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1fd40 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1fd50 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1fd60 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1fd70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1fd80 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
1fd90 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1fda0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1fdb0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1fdc0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1fdd0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1fde0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1fdf0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1fe00 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1fe10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fe20 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1fe30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1fe40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1fe50 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1fe60 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1fe70 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1fe80 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1fe90 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
1fea0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1feb0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1fec0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1fed0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1fee0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1fef0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1ff00 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1ff10 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1ff20 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1ff30 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1ff40 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1ff50 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1ff60 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1ff70 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1ff80 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1ff90 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1ffa0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
1ffb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1ffc0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1ffd0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1ffe0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
1fff0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
20000 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
20010 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
20020 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
20030 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
20040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20050 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
20060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20070 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
20080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20090 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
200a0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
200b0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
200c0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
200d0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
200e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
200f0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
20100 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
20110 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
20120 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20130 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
20140 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
20150 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
20160 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
20170 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
20180 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
20190 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
201a0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
201b0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
201c0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
201d0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
201e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
201f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
20200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
20210 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
20220 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
20230 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
20240 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
20250 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
20260 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
20270 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
20280 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
20290 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
202a0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
202b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
202c0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
202d0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
202e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
202f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20300 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
20310 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
20320 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
20330 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20340 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
20350 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
20360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20370 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
20380 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20390 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
203a0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
203b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
203c0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
203d0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
203e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
203f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
20400 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
20410 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20420 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
20430 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
20440 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
20450 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
20460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20470 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20480 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
20490 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
204a0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
204b0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
204c0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
204d0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
204e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
204f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
20500 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20510 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20520 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
20530 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
20540 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
20550 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
20560 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
20570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20580 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
20590 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
205a0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
205b0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
205c0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
205d0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
205e0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
205f0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
20600 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
20610 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
20620 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
20630 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
20640 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
20650 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
20660 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
20670 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
20680 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
20690 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
206a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
206b0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
206c0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
206d0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
206e0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
206f0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
20700 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
20710 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
20720 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
20730 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
20740 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
20750 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
20760 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
20770 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
20780 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
20790 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
207a0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
207b0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
207c0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
207d0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
207e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
207f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
20800 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
20810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20820 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
20830 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
20840 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20850 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
20860 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20870 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
20880 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
20890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
208a0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
208b0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
208c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
208d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
208e0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
208f0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
20900 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
20910 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
20920 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
20930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
20940 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
20950 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
20960 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
20970 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
20980 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
20990 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
209a0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
209b0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
209c0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
209d0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
209e0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
209f0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
20a00 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
20a10 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
20a20 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
20a30 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
20a40 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
20a50 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
20a60 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
20a70 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
20a80 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
20a90 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
20aa0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
20ab0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
20ac0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
20ad0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
20ae0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
20af0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
20b00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
20b10 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
20b20 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
20b30 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
20b40 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
20b50 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
20b60 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
20b70 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
20b80 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
20b90 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
20ba0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
20bb0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
20bc0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
20bd0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
20be0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20bf0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
20c00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20c10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
20c20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
20c30 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
20c40 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
20c50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
20c60 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
20c70 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
20c80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
20c90 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
20ca0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
20cb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20cc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20cd0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
20ce0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
20cf0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
20d00 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
20d10 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
20d20 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
20d30 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
20d40 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
20d50 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
20d60 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
20d70 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
20d80 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
20d90 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
20da0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
20db0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
20dc0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
20dd0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
20de0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
20df0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
20e00 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
20e10 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
20e20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
20e30 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
20e40 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
20e50 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
20e60 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
20e70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20e80 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
20e90 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20ea0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20eb0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20ec0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20ed0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20ee0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20ef0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20f00 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
20f10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
20f20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
20f30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
20f40 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
20f50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20f60 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
20f70 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
20f80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
20f90 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
20fa0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
20fb0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
20fc0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
20fd0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
20fe0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
20ff0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
21000 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
21010 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
21020 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
21030 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
21040 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
21050 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
21060 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
21070 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
21080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21090 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
210a0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
210b0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
210c0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
210d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
210e0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
210f0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
21100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21110 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
21120 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
21130 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
21140 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
21150 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
21160 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
21170 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
21180 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21190 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
211a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
211b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
211c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
211d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
211e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
211f0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
21200 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
21210 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
21220 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
21230 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
21240 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
21250 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
21260 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
21270 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
21280 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
21290 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
212a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
212b0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
212c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
212d0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
212e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
212f0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
21300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
21320 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
21330 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
21340 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
21350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21360 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
21370 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
21380 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
21390 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
213a0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
213b0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
213c0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
213d0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
213e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
213f0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
21400 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
21410 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
21420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21430 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
21440 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
21450 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
21460 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c  til the next cal
21470 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
21480 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72  column_name() or
21490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
214a0 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20  name16() on the 
214b0 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a  same column..**.
214c0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
214d0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
214e0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
214f0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
21500 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
21510 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
21520 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
21530 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
21540 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
21550 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
21560 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ed..**.** ^The n
21570 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
21580 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
21590 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
215a0 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
215b0 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
215c0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
215d0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
215e0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
215f0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
21600 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
21610 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
21620 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
21630 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
21640 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
21650 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   next..*/.const 
21660 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21670 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
21680 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
21690 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
216a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
216b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
216c0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
216d0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
216e0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
216f0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
21700 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
21710 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
21720 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  s to determine t
21730 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  he database, tab
21740 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65  le, and.** table
21750 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
21760 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20  the origin of a 
21770 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c  particular resul
21780 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b  t column in.** [
21790 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
217a0 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  t..** ^The name 
217b0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
217c0 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
217d0 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
217e0 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
217f0 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
21800 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
21810 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69  _database_ routi
21820 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  nes return.** th
21830 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c  e database name,
21840 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75   the _table_ rou
21850 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
21860 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64   table name, and
21870 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20  .** the origin_ 
21880 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21890 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e  the column name.
218a0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
218b0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
218c0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
218d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
218e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
218f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21900 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
21910 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
21920 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
21930 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
21940 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
21950 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
21960 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
21970 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
21980 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
21990 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
219a0 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
219b0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
219c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
219d0 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
219e0 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
219f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21a00 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
21a10 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
21a20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
21a30 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
21a40 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
21a50 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
21a60 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
21a70 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
21a80 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
21a90 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
21aa0 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
21ab0 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
21ac0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
21ad0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
21ae0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
21af0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
21b00 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
21b10 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
21b20 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
21b30 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
21b40 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
21b50 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
21b60 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
21b70 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
21b80 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
21b90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21ba0 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
21bb0 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
21bc0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
21bd0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
21be0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
21bf0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
21c00 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
21c10 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
21c20 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
21c30 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
21c40 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
21c50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
21c60 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
21c70 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
21c80 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
21c90 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
21ca0 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
21cb0 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
21cc0 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
21cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
21ce0 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
21cf0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
21d00 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
21d10 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
21d20 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
21d30 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
21d40 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
21d50 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
21d60 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
21d70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
21d80 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
21d90 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
21da0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
21db0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
21dc0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
21dd0 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
21de0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
21df0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
21e00 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
21e10 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
21e20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
21e30 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
21e40 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
21e50 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
21e60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21e70 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
21e80 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
21e90 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
21ea0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
21eb0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
21ec0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
21ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
21ee0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
21ef0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21f00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21f10 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
21f20 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
21f30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
21f40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21f50 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
21f60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
21f70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
21f80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21f90 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
21fa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
21fb0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
21fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
21fd0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
21fe0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21ff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
22000 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
22010 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
22020 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
22030 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
22040 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
22050 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
22060 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
22070 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
22080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22090 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
220a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
220b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
220c0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
220d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
220e0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
220f0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
22100 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
22110 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
22120 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
22130 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
22140 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
22150 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
22160 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
22170 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
22180 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
22190 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
221a0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
221b0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
221c0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
221d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
221e0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
221f0 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
22200 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
22210 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
22220 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
22230 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
22240 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
22250 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
22260 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
22270 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
22280 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
22290 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
222a0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
222b0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
222c0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
222d0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
222e0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
222f0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
22300 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
22310 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
22320 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
22330 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
22340 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
22350 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
22360 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
22370 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
22380 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
22390 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
223a0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
223b0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
223c0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
223d0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
223e0 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
223f0 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
22400 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
22410 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
22420 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
22430 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
22440 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
22450 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
22460 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
22470 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
22480 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
22490 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
224a0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
224b0 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  alues..*/.const 
224c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
224d0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
224e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
224f0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
22500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
22510 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
22520 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
22530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
22540 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
22550 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
22560 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
22570 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
22580 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
22590 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
225a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
225b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
225c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
225d0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
225e0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
225f0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
22600 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
22610 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
22620 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
22630 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
22640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
22650 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
22660 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
22670 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
22680 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
22690 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
226a0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
226b0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
226c0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
226d0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
226e0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
226f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
22700 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22710 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
22720 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22730 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
22740 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
22750 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
22760 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
22770 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22780 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
22790 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
227a0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
227b0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
227c0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
227d0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
227e0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
227f0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
22800 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
22810 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
22820 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
22830 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
22840 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
22850 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
22860 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
22870 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
22880 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
22890 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
228a0 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
228b0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
228c0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
228d0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
228e0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
228f0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
22900 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
22910 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
22920 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
22930 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
22940 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
22950 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
22960 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
22970 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
22980 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
22990 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
229a0 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
229b0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
229c0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
229d0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
229e0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
229f0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
22a00 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
22a10 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
22a20 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
22a30 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
22a40 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
22a50 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
22a60 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
22a70 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
22a80 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
22a90 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
22aa0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
22ab0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
22ac0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
22ad0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
22ae0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
22af0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
22b00 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
22b10 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
22b20 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
22b30 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
22b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
22b50 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
22b60 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
22b70 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
22b80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
22b90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
22ba0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
22bb0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
22bc0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
22bd0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
22be0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
22bf0 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
22c00 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
22c10 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
22c20 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
22c30 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
22c40 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
22c50 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
22c60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
22c70 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
22c80 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
22c90 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
22ca0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
22cb0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
22cc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
22cd0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
22ce0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
22cf0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
22d00 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
22d10 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
22d20 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
22d30 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
22d40 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
22d50 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
22d60 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
22d70 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
22d80 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
22d90 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
22da0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
22db0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
22dc0 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
22dd0 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
22de0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
22df0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
22e00 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
22e10 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
22e20 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
22e30 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
22e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22e50 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
22e60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22e70 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
22e80 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
22e90 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22ea0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
22eb0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
22ec0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
22ed0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
22ee0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
22ef0 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
22f00 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
22f10 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
22f20 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
22f30 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
22f40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22f50 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
22f60 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
22f70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
22f80 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
22f90 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
22fa0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
22fb0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
22fc0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
22fd0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
22fe0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
22ff0 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
23000 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23010 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
23020 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
23030 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
23040 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
23050 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
23060 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
23070 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
23080 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
23090 36 2e 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72  6.23.1, it was r
230a0 65 71 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72  equired.** after
230b0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
230c0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
230d0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
230e0 4c 49 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a  LITE_ROW] that.*
230f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
23100 28 29 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ()] be called be
23110 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
23120 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
23130 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
23140 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
23150 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
23160 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69  _reset()] in thi
23170 73 20 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72  s way would.** r
23180 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
23190 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
231a0 72 6e 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rn from sqlite3_
231b0 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
231c0 65 72 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  er.** version 3.
231d0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
231e0 73 74 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c  step() began cal
231f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
23200 73 65 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d  set()] .** autom
23210 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
23220 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
23230 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
23240 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
23250 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e  SE].  .**.** <b>
23260 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
23270 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
23280 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
23290 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
232a0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
232b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
232c0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
232d0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
232e0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
232f0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
23300 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
23310 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
23320 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
23330 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
23340 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
23350 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23360 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
23370 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
23380 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
23390 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
233a0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
233b0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
233c0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
233d0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
233e0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
233f0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
23400 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
23410 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
23420 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
23430 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
23440 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
23450 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
23460 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
23470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23480 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
23490 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
234a0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
234b0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
234c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
234d0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
234e0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
234f0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
23500 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
23510 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
23520 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
23530 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
23540 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
23550 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
23560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
23570 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
23580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23590 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
235a0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
235b0 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt set.**.** ^Th
235c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
235d0 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
235e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
235f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23600 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
23610 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
23620 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
23630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23640 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
23650 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
23660 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
23670 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
23680 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
23690 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
236a0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
236b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
236c0 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
236d0 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
236e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
236f0 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
23700 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
23710 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
23720 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
23730 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
23740 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  pointer..**.** S
23750 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
23760 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
23770 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
23780 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
23790 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
237a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
237b0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
237c0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
237d0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
237e0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
237f0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
23800 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
23810 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
23820 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
23830 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
23840 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
23850 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
23860 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
23870 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
23880 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
23890 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
238a0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
238b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
238c0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
238d0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
238e0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
238f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
23900 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
23910 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
23920 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
23930 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
23940 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
23950 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
23960 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
23970 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
23980 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
23990 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
239a0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
239b0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
239c0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
239d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
239e0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
239f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
23a00 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
23a10 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
23a20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
23a30 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
23a40 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
23a50 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
23a60 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
23a70 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
23a80 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
23a90 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
23aa0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
23ab0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
23ac0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
23ad0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
23ae0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
23af0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
23b00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
23b10 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
23b20 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
23b30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
23b40 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
23b50 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
23b60 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
23b70 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
23b80 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
23b90 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
23ba0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
23bb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
23bc0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
23bd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23be0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
23bf0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
23c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
23c10 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
23c20 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
23c30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23c40 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
23c50 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
23c60 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
23c70 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
23c80 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
23c90 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
23ca0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
23cb0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
23cc0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
23cd0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
23ce0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
23cf0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
23d00 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
23d10 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
23d20 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
23d30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
23d40 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
23d50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
23d60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
23d70 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
23d80 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
23d90 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
23da0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
23db0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
23dc0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
23dd0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
23de0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
23df0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
23e00 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
23e10 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
23e20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23e30 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
23e40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
23e50 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
23e60 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
23e70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
23e80 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
23e90 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
23ea0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
23eb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
23ec0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
23ed0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23ee0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23ef0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
23f00 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
23f10 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
23f20 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
23f30 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
23f40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
23f50 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
23f60 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
23f70 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
23f80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23f90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
23fa0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
23fb0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
23fc0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
23fd0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
23fe0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
23ff0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
24000 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
24010 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
24020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24030 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
24040 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
24050 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
24060 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
24070 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
24080 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
24090 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
240a0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
240b0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
240c0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
240d0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
240e0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
240f0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
24100 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
24110 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
24120 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
24130 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
24140 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
24150 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
24160 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
24170 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
24180 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
24190 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
241a0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
241b0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
241c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
241d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
241e0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
241f0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
24200 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24210 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
24220 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
24230 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
24240 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
24250 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24260 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
24270 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
24280 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
24290 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
242a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
242b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
242c0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
242d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
242e0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
242f0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
24300 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
24310 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
24320 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24330 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
24340 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
24350 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
24360 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
24370 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
24380 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
24390 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
243a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
243b0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
243c0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
243d0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
243e0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
243f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
24400 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
24410 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
24420 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
24430 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
24440 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
24450 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24460 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
24470 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
24480 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
24490 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
244a0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
244b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
244c0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
244d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
244e0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
244f0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
24500 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
24510 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
24520 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
24530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24540 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
24550 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
24560 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
24570 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
24580 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
24590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
245a0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
245b0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
245c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
245d0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
245e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
245f0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
24600 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
24610 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
24620 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
24630 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
24640 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
24650 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
24660 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
24670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24680 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
24690 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
246a0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
246b0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
246c0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
246d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
246e0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
246f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
24700 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
24710 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
24720 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
24730 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
24740 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
24750 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
24760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
24770 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
24780 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
24790 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
247a0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
247b0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
247c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
247d0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
247e0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
247f0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24800 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
24810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24820 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
24830 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
24840 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
24850 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
24860 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
24870 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
24880 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
24890 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
248a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
248b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  er..**.** ^The o
248c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
248d0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
248e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
248f0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
24900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
24910 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
24920 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
24930 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
24940 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
24950 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
24960 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
24970 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
24980 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
24990 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
249a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
249b0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
249c0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
249d0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
249e0 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
249f0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
24a00 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
24a10 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
24a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
24a30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
24a40 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
24a50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
24a60 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
24a70 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
24a80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
24a90 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24aa0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
24ab0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
24ac0 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
24ad0 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
24ae0 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
24af0 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
24b00 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
24b10 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
24b20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
24b30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
24b40 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
24b50 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
24b60 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
24b70 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
24b80 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
24b90 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
24ba0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
24bb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
24bc0 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
24bd0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
24be0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
24bf0 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
24c00 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
24c10 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
24c20 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
24c30 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
24c40 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
24c50 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
24c60 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
24c70 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
24c80 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
24c90 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
24ca0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
24cb0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
24cc0 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
24cd0 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
24ce0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
24cf0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
24d00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
24d10 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
24d20 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
24d30 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
24d40 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
24d50 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
24d60 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
24d70 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
24d80 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
24d90 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
24da0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
24db0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
24dc0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
24dd0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
24de0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
24df0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
24e00 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
24e10 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
24e20 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
24e30 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
24e40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
24e50 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
24e60 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
24e70 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
24e80 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
24e90 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
24ea0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
24eb0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
24ec0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
24ed0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
24ee0 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
24ef0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
24f00 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
24f10 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
24f20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
24f30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
24f40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
24f50 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
24f60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
24f70 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
24f80 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
24f90 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
24fa0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
24fb0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
24fc0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
24fd0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
24fe0 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
24ff0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
25000 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
25010 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
25020 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
25030 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
25040 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
25050 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
25060 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
25070 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
25080 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
25090 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
250a0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
250b0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
250c0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
250d0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
250e0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
250f0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
25100 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
25110 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
25120 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
25130 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
25140 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
25150 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
25160 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
25170 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
25180 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
25190 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
251a0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
251b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
251c0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
251d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
251e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
251f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25200 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
25210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25220 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
25230 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
25240 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
25250 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
25260 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
25270 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
25280 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
25290 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
252a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
252b0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
252c0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
252d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
252e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
252f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
25300 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
25310 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
25320 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
25330 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
25340 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
25350 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
25360 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
25370 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
25380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25390 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
253a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
253b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
253c0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
253d0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
253e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
253f0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
25400 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
25410 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
25420 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
25430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
25440 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
25450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25460 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
25470 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
25480 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
25490 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
254a0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
254b0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
254c0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
254d0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
254e0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
254f0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
25500 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
25510 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
25520 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
25530 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
25540 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
25550 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
25560 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73  inter references
25570 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
25580 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
25590 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
255a0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
255b0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
255c0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
255d0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
255e0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
255f0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
25600 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
25610 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
25620 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
25630 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
25640 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
25650 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
25660 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
25670 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
25680 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
25690 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
256a0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
256b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
256c0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
256d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
256e0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
256f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25700 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
25710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25720 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
25730 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
25740 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
25750 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
25760 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25770 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
25780 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
25790 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
257a0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
257b0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
257c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
257d0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
257e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
257f0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
25800 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
25810 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
25820 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
25830 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
25840 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
25850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25860 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
25870 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
25880 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
25890 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
258a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
258b0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
258c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
258d0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
258e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
258f0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
25900 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
25910 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
25920 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
25930 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
25940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25950 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
25960 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
25970 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
25980 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
25990 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
259a0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
259b0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
259c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
259d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
259e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
259f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
25a00 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
25a10 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
25a20 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
25a30 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
25a40 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
25a50 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
25a60 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
25a70 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
25a80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25a90 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
25aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
25ab0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
25ac0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
25ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d  ..**.** ^(If a m
25ae0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
25af0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
25b00 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
25b10 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
25b20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
25b30 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
25b40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
25b50 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
25b60 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
25b70 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
25b80 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
25b90 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
25ba0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
25bb0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
25bc0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
25bd0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
25be0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
25bf0 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63  E_NOMEM].)^.*/.c
25c00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
25c10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
25c20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25c30 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
25c40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25c50 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
25c60 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
25c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25c80 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
25c90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
25ca0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
25cb0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
25cc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25cd0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
25ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
25cf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25d00 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
25d10 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
25d20 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
25d30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
25d40 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
25d50 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
25d60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
25d70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25d80 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
25d90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25da0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
25db0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25dc0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
25dd0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
25de0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
25df0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
25e00 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
25e10 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
25e20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25e30 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
25e40 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
25e50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
25e60 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
25e70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
25e80 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
25e90 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
25ea0 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
25eb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
25ec0 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
25ed0 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
25ee0 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
25ef0 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
25f00 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
25f10 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
25f20 64 2e 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e  d. ^If execution
25f30 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
25f40 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
25f50 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
25f60 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
25f70 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
25f80 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
25f90 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
25fa0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
25fb0 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65  point during the
25fc0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
25fd0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25fe0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20  tatement].  ^If 
25ff0 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
26000 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
26010 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
26020 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
26030 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
26040 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
26050 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
26060 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
26070 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
26080 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
26090 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61  ^Incomplete upda
260a0 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
260b0 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
260c0 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
260d0 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
260e0 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
260f0 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
26100 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
26110 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
26120 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f  QLITE_ABORT]..*/
26130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
26140 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
26150 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
26170 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
26180 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
26190 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
261a0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
261b0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
261c0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
261d0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
261e0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
261f0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
26200 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
26210 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
26220 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
26230 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
26240 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
26250 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
26260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
26270 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
26280 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
26290 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
262a0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
262b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
262c0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
262d0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
262e0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
262f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
26300 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
26310 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26320 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
26330 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
26340 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
26350 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
26360 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
26370 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26380 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
26390 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
263a0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
263b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
263c0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
263d0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
263e0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
263f0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
26400 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
26410 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
26420 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
26430 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
26440 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
26450 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
26460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26470 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
26480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26490 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
264a0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
264b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
264c0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
264d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
264e0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
264f0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
26500 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
26510 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
26520 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
26530 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
26540 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
26550 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
26560 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
26570 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
26580 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
26590 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
265a0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
265b0 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
265c0 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
265d0 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
265e0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
265f0 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
26600 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
26610 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26620 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
26630 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
26640 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26650 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
26660 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
26670 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
26680 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
26690 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
266a0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
266b0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
266c0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
266d0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
266e0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
266f0 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
26700 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
26710 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
26720 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
26730 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
26740 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
26750 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
26760 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
26770 20 74 68 65 20 74 68 65 20 73 65 63 6f 6e 64 20   the the second 
26780 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
26790 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
267a0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
267b0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
267c0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
267d0 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
267e0 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
267f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
26800 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
26810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
26820 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
26830 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26840 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
26850 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
26860 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
26870 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
26880 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
26890 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
268a0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
268b0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
268c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
268d0 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
268e0 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
268f0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
26900 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
26910 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
26920 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
26930 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
26940 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
26950 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
26960 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
26970 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
26980 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
26990 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
269a0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
269b0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
269c0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
269d0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
269e0 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
269f0 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
26a00 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
26a10 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
26a20 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
26a30 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
26a40 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
26a50 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
26a60 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
26a70 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
26a80 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
26a90 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
26aa0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
26ab0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
26ac0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
26ad0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
26ae0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
26af0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
26b00 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
26b10 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
26b20 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
26b30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26b40 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
26b50 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
26b60 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
26b70 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
26b80 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
26b90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
26ba0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
26bb0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
26bc0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
26bd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
26be0 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
26bf0 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
26c00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
26c10 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
26c20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
26c30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
26c40 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
26c50 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
26c60 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
26c70 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
26c80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
26c90 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
26ca0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
26cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
26cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
26cd0 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
26ce0 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
26cf0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
26d00 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
26d10 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
26d20 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
26d30 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
26d40 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
26d50 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
26d60 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
26d70 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
26d80 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
26d90 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
26da0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26db0 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
26dc0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
26dd0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
26de0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
26df0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
26e00 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
26e10 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
26e20 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
26e30 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
26e40 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
26e50 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
26e60 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
26e70 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
26e80 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
26e90 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
26ea0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
26eb0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
26ec0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
26ed0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
26ee0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
26ef0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
26f00 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
26f10 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
26f20 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
26f30 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
26f40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
26f50 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
26f60 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
26f70 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
26f80 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
26f90 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
26fa0 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
26fb0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
26fc0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
26fd0 5e 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69  ^The seventh, ei
26fe0 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
26ff0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
27000 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
27010 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
27020 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
27030 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
27040 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
27050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
27060 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
27070 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
27080 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
27090 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
270a0 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
270b0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
270c0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
270d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
270e0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
270f0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
27100 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
27110 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
27120 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
27130 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
27140 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
27150 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
27160 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
27170 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
27180 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
27190 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
271a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
271b0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 65 72 73  ass NULL poiners
271c0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
271d0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
271e0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  acks..**.** ^It 
271f0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
27200 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
27210 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
27220 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
27230 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
27240 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
27250 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
27260 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
27270 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
27280 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
27290 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
272a0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
272b0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
272c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
272d0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
272e0 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
272f0 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
27300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
27310 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
27320 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
27330 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
27340 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
27350 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
27360 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
27370 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
27380 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
27390 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
273a0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
273b0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
273c0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
273d0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
273e0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
273f0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
27400 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
27410 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
27420 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
27430 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
27440 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
27450 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
27460 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
27470 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
27480 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
27490 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
274a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
274b0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
274c0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
274d0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
274e0 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
274f0 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
27500 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
27510 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
27520 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27530 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68  unctions..** ^Th
27540 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
27550 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27560 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
27570 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
27580 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
27590 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
275a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
275b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
275c0 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
275d0 0a 2a 2a 20 5e 53 75 62 73 65 71 75 65 6e 74 20  .** ^Subsequent 
275e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
275f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66  ned functions of
27600 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f   the same name o
27610 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a  nly override .**
27620 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69   prior applicati
27630 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27640 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e  ions that are an
27650 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72   exact match for
27660 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
27670 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  f parameters and
27680 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64   preferred encod
27690 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ing..**.** ^An a
276a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
276b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
276c0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
276d0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
276e0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
276f0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
27700 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
27710 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
27720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
27730 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
27740 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
27750 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
27760 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
27770 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
27780 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
27790 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
277a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
277b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
277c0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
277d0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
277e0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
277f0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
27800 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
27810 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
27820 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
27830 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
27840 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
27850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
27860 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
27870 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
27880 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
27890 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
278a0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
278b0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
278c0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
278d0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
278e0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
278f0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
27900 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
27910 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
27920 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
27930 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
27940 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
27950 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
27960 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
27970 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
27980 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
27990 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
279a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
279b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
279c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
279d0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
279e0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
279f0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
27a00 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
27a10 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
27a20 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
27a30 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
27a40 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
27a50 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
27a60 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
27a70 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
27a80 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
27a90 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
27aa0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
27ab0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
27ac0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
27ad0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
27ae0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
27af0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
27b00 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
27b10 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
27b20 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
27b30 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
27b40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
27b50 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
27b60 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
27b70 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
27b80 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
27b90 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
27ba0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
27bb0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
27bc0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
27bd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
27be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27bf0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
27c00 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
27c10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27c20 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
27c30 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
27c40 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
27c50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
27c60 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
27c70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27c80 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
27c90 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
27ca0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
27cb0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
27cc0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
27cd0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
27ce0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
27cf0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
27d00 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
27d10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
27d20 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
27d30 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
27d40 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
27d50 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
27d60 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
27d70 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
27d80 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
27d90 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
27da0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
27db0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
27dc0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
27dd0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
27de0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
27df0 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
27e00 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
27e10 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
27e20 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
27e30 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
27e40 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
27e50 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
27e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
27e70 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
27e80 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
27e90 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
27ea0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
27eb0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
27ec0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
27ed0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
27ee0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
27ef0 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
27f00 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
27f10 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
27f20 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
27f30 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
27f40 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
27f50 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
27f60 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
27f70 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
27f80 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
27f90 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
27fa0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
27fb0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
27fc0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
27fd0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
27fe0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
27ff0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
28000 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
28010 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
28020 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
28030 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
28040 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
28050 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
28060 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
28070 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
28080 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
28090 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
280a0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
280b0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
280c0 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
280d0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
280e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
280f0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
28100 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28110 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
28120 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
28130 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
28140 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
28150 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
28160 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
28170 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
28180 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
28190 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
281a0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
281b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
281c0 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
281d0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
281e0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
281f0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
28200 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
28210 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
28220 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
28230 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
28240 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
28250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28260 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
28270 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
28280 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
28290 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
282a0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
282b0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
282c0 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
282d0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
282e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
282f0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
28300 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
28310 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
28320 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
28330 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
28340 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
28350 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
28360 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
28370 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
28380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
28390 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
283a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
283b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
283c0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
283d0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
283e0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
283f0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
28400 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
28410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
28420 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
28430 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
28440 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
28450 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
28460 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
28470 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
28480 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28490 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
284a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
284b0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
284c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
284d0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
284e0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
284f0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
28500 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
28510 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
28520 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
28530 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
28540 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
28550 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
28560 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
28570 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
28580 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
28590 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
285a0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
285b0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
285c0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
285d0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
285e0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
285f0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
28600 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
28610 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
28620 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
28630 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
28640 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
28650 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
28660 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
28670 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
28680 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
28690 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
286a0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
286b0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
286c0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
286d0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
286e0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
286f0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
28700 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
28710 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
28720 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
28730 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
28740 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
28750 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
28760 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
28770 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
28780 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
28790 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
287a0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
287b0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
287c0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
287d0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
287e0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
287f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28800 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
28810 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28820 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
28830 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
28840 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
28850 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
28860 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
28870 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
28880 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
28890 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
288a0 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
288b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
288c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
288d0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
288e0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
288f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28900 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28910 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
28920 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
28930 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
28940 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
28950 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28960 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
28970 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
28980 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
28990 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
289a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
289b0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
289c0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
289d0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
289e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
289f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
28a00 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
28a10 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
28a20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28a30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
28a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
28a50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28a60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
28a70 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
28a80 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
28a90 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
28aa0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
28ab0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
28ac0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
28ad0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
28ae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
28af0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
28b00 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
28b10 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
28b20 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
28b30 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
28b40 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
28b50 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
28b60 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
28b70 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
28b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
28b90 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
28ba0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28bb0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
28bc0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
28bd0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
28be0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
28bf0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
28c00 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
28c10 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
28c20 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
28c30 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
28c40 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
28c50 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
28c60 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
28c70 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
28c80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
28c90 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
28ca0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
28cb0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
28cc0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
28cd0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
28ce0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
28cf0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28d00 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
28d10 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
28d20 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
28d30 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
28d40 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
28d50 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
28d60 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
28d70 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
28d80 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
28d90 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
28da0 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
28db0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
28dc0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
28dd0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
28de0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
28df0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
28e00 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
28e10 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
28e20 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
28e30 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
28e40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28e50 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
28e60 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
28e70 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
28e80 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
28e90 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
28ea0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
28eb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
28ec0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28ed0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28ee0 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
28ef0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
28f00 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
28f10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
28f20 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
28f30 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
28f40 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
28f50 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
28f60 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
28f70 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
28f80 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
28f90 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
28fa0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
28fb0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
28fc0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
28fd0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
28fe0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
28ff0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
29000 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
29010 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
29020 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
29030 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
29040 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
29050 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
29060 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
29070 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
29080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
29090 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
290a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
290b0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
290c0 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
290d0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
290e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
290f0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
29100 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
29110 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
29120 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
29130 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
29140 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
29150 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
29160 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
29170 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
29180 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
29190 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
291a0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
291b0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
291c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
291d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
291e0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
291f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
29200 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
29210 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
29220 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
29230 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
29240 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
29250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29260 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
29270 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
29280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
29290 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
292a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
292b0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
292c0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
292d0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
292e0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
292f0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29300 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
29310 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
29320 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
29330 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29340 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
29350 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
29360 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
29370 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
29380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
29390 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
293a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
293b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
293c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
293d0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
293e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
293f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
29400 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
29410 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
29420 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
29430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
29440 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
29450 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
29460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29470 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
29480 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
29490 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
294a0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
294b0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
294c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
294d0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
294e0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
294f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29500 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
29510 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29520 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
29530 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
29540 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
29550 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
29560 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
29570 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
29580 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
29590 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
295a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
295b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
295c0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
295d0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
295e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
295f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
29600 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
29610 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
29620 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
29630 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
29640 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
29650 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
29660 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
29670 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
29680 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
29690 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
296a0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
296b0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
296c0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
296d0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
296e0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
296f0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
29700 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
29710 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
29720 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
29730 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
29740 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
29750 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
29760 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
29770 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
29780 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
29790 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
297a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
297b0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
297c0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
297d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
297e0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
297f0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
29800 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
29810 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
29820 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
29830 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
29840 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
29850 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
29860 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
29870 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
29880 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
29890 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
298a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
298b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
298c0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
298d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
298e0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
298f0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
29900 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
29910 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
29920 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
29930 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
29940 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
29950 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29960 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
29970 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
29980 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
29990 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
299a0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
299b0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
299c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
299d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
299e0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
299f0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
29a00 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
29a10 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
29a20 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
29a30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
29a40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
29a50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
29a60 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
29a70 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
29a80 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
29a90 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
29aa0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
29ab0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
29ac0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
29ad0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
29ae0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29af0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
29b00 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
29b10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
29b20 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
29b30 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
29b40 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
29b50 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
29b60 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
29b70 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
29b80 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
29b90 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
29ba0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
29bb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29bc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
29bd0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
29be0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
29bf0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
29c00 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
29c10 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
29c20 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
29c30 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
29c40 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
29c50 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
29c60 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
29c70 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
29c80 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
29c90 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
29ca0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
29cb0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
29cc0 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
29cd0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
29ce0 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
29cf0 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
29d00 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
29d10 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
29d20 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
29d30 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
29d40 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
29d50 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
29d60 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
29d70 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
29d80 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
29d90 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
29da0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
29db0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
29dc0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
29dd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
29de0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
29df0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
29e00 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
29e10 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
29e20 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
29e30 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
29e40 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
29e50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29e60 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
29e70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
29e80 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
29e90 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
29ea0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
29eb0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
29ec0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
29ed0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
29ee0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
29ef0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
29f00 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
29f10 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
29f20 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
29f30 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
29f40 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
29f50 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
29f60 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
29f70 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
29f80 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
29f90 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
29fa0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
29fb0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
29fc0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
29fd0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
29fe0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
29ff0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2a000 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2a010 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
2a020 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2a030 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2a040 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2a050 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2a060 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2a070 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2a080 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2a090 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2a0a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2a0b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2a0c0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2a0d0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2a0e0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2a0f0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2a100 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2a110 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2a120 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2a130 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2a140 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2a150 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2a160 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2a170 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2a180 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2a190 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2a1a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a1b0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2a1c0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2a1d0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2a1e0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2a1f0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2a200 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2a210 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a220 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
2a230 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
2a240 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
2a250 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
2a260 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
2a270 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
2a280 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
2a290 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a2a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2a2b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a2c0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
2a2d0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2a2e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
2a2f0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
2a300 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
2a310 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
2a320 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
2a330 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
2a340 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
2a350 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2a360 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2a370 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2a380 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
2a390 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
2a3a0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2a3b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2a3c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2a3d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a3e0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2a3f0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2a400 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2a410 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a420 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2a430 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2a440 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2a450 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2a460 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2a470 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2a480 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2a490 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2a4a0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2a4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a4c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2a4d0 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2a4e0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2a4f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2a500 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a510 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2a520 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2a530 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2a540 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2a550 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2a560 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2a570 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2a580 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a590 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
2a5a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2a5b0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2a5c0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2a5d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a5e0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
2a5f0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
2a600 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
2a610 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
2a620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a630 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a640 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2a650 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2a660 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
2a670 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
2a680 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2a690 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
2a6a0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
2a6b0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
2a6c0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
2a6d0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
2a6e0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
2a6f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2a700 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2a710 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
2a720 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
2a730 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
2a740 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
2a750 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
2a760 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
2a770 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2a780 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
2a790 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
2a7a0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2a7b0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2a7c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2a7d0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
2a7e0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
2a7f0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
2a800 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2a810 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2a820 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2a830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a840 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
2a850 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2a860 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
2a870 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
2a880 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
2a890 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2a8a0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2a8b0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2a8c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2a8d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2a8e0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2a8f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2a900 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2a910 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2a920 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
2a930 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2a940 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
2a950 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
2a960 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2a970 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
2a980 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a990 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2a9a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2a9b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2a9c0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
2a9d0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2a9e0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2a9f0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2aa00 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2aa10 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2aa20 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2aa30 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2aa40 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2aa50 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2aa60 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
2aa70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2aa80 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2aa90 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2aaa0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2aab0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2aac0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2aad0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2aae0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
2aaf0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
2ab00 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
2ab10 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
2ab20 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2ab30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ab40 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2ab50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2ab60 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
2ab70 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
2ab80 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
2ab90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2aba0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
2abb0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2abc0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2abd0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2abe0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
2abf0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
2ac00 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
2ac10 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2ac20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2ac30 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
2ac40 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2ac50 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2ac60 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2ac70 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
2ac80 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
2ac90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2aca0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
2acb0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2acc0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2acd0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2ace0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2acf0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2ad00 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
2ad10 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2ad20 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2ad30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2ad40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ad50 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
2ad60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2ad70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2ad80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ad90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ada0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
2adb0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2adc0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2add0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2ade0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2adf0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2ae00 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2ae10 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2ae20 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2ae30 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ae40 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2ae50 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
2ae60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ae70 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2ae80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2ae90 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
2aea0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2aeb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2aec0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2aed0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2aee0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2aef0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2af00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2af10 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2af20 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2af30 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2af40 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2af50 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2af60 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2af70 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2af80 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2af90 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2afa0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
2afb0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2afc0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2afd0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2afe0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2aff0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2b000 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2b010 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
2b020 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2b030 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2b040 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2b050 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2b060 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2b070 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
2b080 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
2b090 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
2b0a0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2b0b0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2b0c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2b0d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2b0e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2b0f0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2b100 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
2b110 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
2b120 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
2b130 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
2b140 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
2b150 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
2b160 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2b170 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
2b180 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b190 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
2b1a0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2b1b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2b1c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2b1d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2b1e0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2b1f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2b200 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
2b210 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2b220 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
2b230 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
2b240 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2b250 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2b260 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
2b270 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2b280 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2b290 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2b2a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2b2b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b2c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2b2d0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
2b2e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2b2f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2b300 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
2b310 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
2b320 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
2b330 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2b340 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
2b350 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
2b360 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
2b370 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
2b380 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2b390 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
2b3a0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
2b3b0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
2b3c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
2b3d0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2b3e0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2b3f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2b400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b410 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2b420 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2b430 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2b440 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2b450 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2b460 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2b470 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2b480 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2b490 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2b4a0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2b4b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2b4c0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2b4d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2b4e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2b4f0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2b500 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2b510 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2b520 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b530 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
2b540 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
2b550 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b560 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
2b570 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
2b580 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
2b590 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2b5a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2b5b0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2b5c0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2b5d0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2b5e0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
2b5f0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
2b600 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
2b610 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
2b620 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
2b630 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
2b640 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2b650 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
2b660 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
2b670 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b680 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2b690 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2b6a0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2b6b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b6c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b6d0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2b6e0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2b6f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2b700 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2b710 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2b720 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2b730 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2b740 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2b750 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2b760 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
2b770 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
2b780 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2b790 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b7a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
2b7b0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
2b7c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2b7d0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
2b7e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2b7f0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
2b800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2b810 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
2b820 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2b830 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2b840 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2b850 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2b860 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2b870 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
2b880 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b890 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
2b8a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2b8b0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
2b8c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b8d0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
2b8e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2b8f0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
2b900 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b910 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
2b920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b930 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2b940 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
2b950 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
2b960 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2b970 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
2b980 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
2b990 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
2b9a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b9b0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
2b9c0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
2b9d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b9e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
2b9f0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
2ba00 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
2ba10 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
2ba20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ba30 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2ba40 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
2ba50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2ba60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
2ba70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2ba80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2ba90 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
2baa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2bab0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2bac0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2bad0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2bae0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
2baf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2bb00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2bb10 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2bb20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2bb30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2bb40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2bb50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2bb60 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2bb70 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2bb80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
2bb90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2bbb0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2bbc0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
2bbd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2bbe0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2bbf0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
2bc00 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
2bc10 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
2bc20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
2bc30 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
2bc40 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
2bc50 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
2bc60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bc70 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
2bc80 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2bc90 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2bca0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
2bcb0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
2bcc0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
2bcd0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
2bce0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
2bcf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2bd00 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
2bd10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bd20 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
2bd30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
2bd40 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2bd50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2bd60 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a   ^In all cases.*
2bd70 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
2bd80 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
2bd90 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2bda0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2bdb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2bdc0 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  may be one of th
2bdd0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
2bde0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
2bdf0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2be00 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2be10 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
2be20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
2be30 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
2be40 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
2be50 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
2be60 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
2be70 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
2be80 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2be90 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d  -endian, or UTF-
2bea0 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72  16 big-endian, r
2beb0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68  espectively. ^Th
2bec0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
2bed0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
2bee0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
2bef0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
2bf00 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a  t the routine.**
2bf10 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2bf20 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73  s to be UTF-16 s
2bf30 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61  trings in the na
2bf40 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2bf50 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   or the.** argum
2bf60 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49  ent can be [SQLI
2bf70 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2bf80 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20  ] if the.** the 
2bf90 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2bfa0 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62  pointers to 16-b
2bfb0 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20  it word aligned 
2bfc0 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54  strings.** of UT
2bfd0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
2bfe0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2bff0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
2c000 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
2c010 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
2c020 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2c030 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
2c040 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ent.  ^If it is 
2c050 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
2c060 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
2c070 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
2c080 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
2c090 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
2c0a0 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 20  not call it any 
2c0b0 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20  more)..** ^Each 
2c0c0 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
2c0d0 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
2c0e0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
2c0f0 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
2c100 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
2c110 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
2c120 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
2c130 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
2c140 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
2c150 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
2c160 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
2c170 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c180 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
2c190 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69  .** ^The remaini
2c1a0 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ng arguments to 
2c1b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2c1c0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
2c1d0 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73   are two strings
2c1e0 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73  ,.** each repres
2c1f0 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67  ented by a (leng
2c200 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61  th, data) pair a
2c210 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68  nd encoded in th
2c220 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68  e encoding.** th
2c230 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73  at was passed as
2c240 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
2c250 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  ent when the col
2c260 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2c270 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  was.** registere
2c280 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  d.  The applicat
2c290 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
2c2a0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
2c2b0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
2c2c0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
2c2d0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
2c2e0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
2c2f0 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
2c300 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
2c310 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
2c320 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
2c330 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
2c340 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NG2)..**.** ^The
2c350 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c360 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
2c370 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
2c380 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c390 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  on().** except t
2c3a0 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20  hat it takes an 
2c3b0 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77  extra argument w
2c3c0 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75  hich is a destru
2c3d0 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ctor for.** the 
2c3e0 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65  collation.  ^The
2c3f0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2c400 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
2c410 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
2c420 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
2c430 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
2c440 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2c450 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
2c460 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
2c470 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2c480 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
2c490 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20  ^Collations are 
2c4a0 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74  destroyed when t
2c4b0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
2c4c0 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
2c4d0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c  s to the.** coll
2c4e0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
2c4f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
2c500 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2c510 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
2c520 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  osed.** using [s
2c530 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
2c540 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c550 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
2c560 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
2c570 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
2c580 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2c590 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2c5a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2c5b0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
2c5c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c5d0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2c5e0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2c5f0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2c600 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2c610 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2c620 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
2c630 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2c640 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
2c650 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2c660 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2c670 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2c680 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2c690 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2c6a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2c6b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2c6c0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
2c6d0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
2c6e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2c6f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
2c700 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2c710 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
2c720 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c730 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2c740 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2c750 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c760 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2c770 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2c780 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
2c790 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
2c7a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
2c7b0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
2c7c0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
2c7d0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
2c7e0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
2c7f0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
2c800 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
2c810 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
2c820 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
2c830 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
2c840 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2c850 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2c860 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
2c870 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
2c880 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
2c890 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
2c8a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2c8b0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2c8c0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
2c8d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
2c8e0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
2c8f0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
2c900 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
2c910 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2c920 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
2c930 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
2c940 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
2c950 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2c960 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
2c970 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
2c980 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
2c990 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
2c9a0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
2c9b0 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
2c9c0 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
2c9d0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
2c9e0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
2c9f0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
2ca00 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
2ca10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2ca20 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
2ca30 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
2ca40 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
2ca50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2ca60 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
2ca70 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
2ca80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2ca90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2caa0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
2cab0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
2cac0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2cad0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
2cae0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
2caf0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
2cb00 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
2cb10 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
2cb20 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
2cb30 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
2cb40 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
2cb50 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
2cb60 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
2cb70 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
2cb80 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
2cb90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2cba0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
2cbb0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
2cbc0 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
2cbd0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
2cbe0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
2cbf0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
2cc00 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
2cc10 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2cc20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2cc30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2cc40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2cc50 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2cc60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2cc70 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69  tion_v2()]..*/.i
2cc80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2cc90 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
2cca0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2ccb0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
2ccc0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2ccd0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2cce0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
2ccf0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2cd00 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2cd10 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2cd20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2cd30 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2cd40 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2cd50 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2cd60 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2cd70 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2cd80 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2cd90 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2cda0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2cdb0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2cdc0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2cdd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2cde0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2cdf0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2ce00 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2ce10 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2ce20 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2ce30 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2ce40 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
2ce50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ce60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ce70 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2ce80 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2ce90 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2cea0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2ceb0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
2cec0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
2ced0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
2cee0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
2cef0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
2cf00 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
2cf10 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
2cf20 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
2cf30 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
2cf40 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
2cf50 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
2cf60 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
2cf70 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
2cf80 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
2cf90 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
2cfa0 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
2cfb0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
2cfc0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
2cfd0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
2cfe0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cff0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2d000 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2d010 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2d020 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2d030 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2d040 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2d050 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2d060 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2d070 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73  or a SEE databas
2d080 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2d090 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2d0a0 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e  f the SEE routin
2d0b0 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f  es will work..*/
2d0c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63  .void sqlite3_ac
2d0d0 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f  tivate_see(.  co
2d0e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50  nst char *zPassP
2d0f0 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20  hrase        /* 
2d100 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73  Activation phras
2d110 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a  e */.);.#endif..
2d120 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e  #ifdef SQLITE_EN
2d130 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a  ABLE_CEROD./*.**
2d140 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74   Specify the act
2d150 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20  ivation key for 
2d160 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65  a CEROD database
2d170 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63  .  Unless .** ac
2d180 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66  tivated, none of
2d190 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69   the CEROD routi
2d1a0 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2d1b0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2d1c0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
2d1d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2d1e0 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2d1f0 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2d200 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2d210 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2d220 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
2d230 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
2d240 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Time.**.** ^The
2d250 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2d260 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
2d270 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
2d280 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
2d290 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
2d2a0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
2d2b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2d2c0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
2d2d0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
2d2e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65 72  .** ^If the oper
2d2f0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
2d300 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
2d310 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
2d320 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
2d330 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
2d340 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
2d350 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
2d360 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
2d370 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54 68  rest second. ^Th
2d380 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
2d390 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
2d3a0 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
2d3b0 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
2d3c0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2d3d0 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
2d3e0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
2d3f0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
2d400 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
2d410 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
2d420 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
2d430 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
2d440 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
2d450 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
2d460 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
2d470 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
2d480 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
2d490 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
2d4a0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
2d4b0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
2d4c0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
2d4d0 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
2d4e0 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
2d4f0 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
2d500 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
2d510 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
2d520 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
2d530 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
2d540 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
2d550 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
2d560 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
2d570 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
2d580 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
2d590 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
2d5a0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
2d5b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
2d5c0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
2d5d0 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
2d5e0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
2d5f0 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
2d600 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
2d610 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
2d620 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
2d630 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2d640 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
2d650 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
2d660 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
2d670 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2d680 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2d690 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
2d6a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d6b0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
2d6c0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
2d6d0 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
2d6e0 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
2d6f0 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
2d700 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2d710 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
2d720 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
2d730 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
2d740 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
2d750 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
2d760 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
2d770 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d780 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
2d790 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
2d7a0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
2d7b0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
2d7c0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2d7d0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2d7e0 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
2d7f0 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
2d800 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
2d810 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2d820 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d830 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
2d840 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
2d850 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2d860 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2d870 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
2d880 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
2d890 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
2d8a0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
2d8b0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
2d8c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2d8d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
2d8e0 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
2d8f0 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
2d900 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
2d910 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
2d920 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
2d930 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
2d940 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
2d950 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
2d960 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
2d970 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
2d980 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
2d990 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2d9a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2d9b0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
2d9c0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
2d9d0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
2d9e0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
2d9f0 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
2da00 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
2da10 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
2da20 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
2da30 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
2da40 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
2da50 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
2da60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
2da70 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
2da80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2da90 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
2daa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dab0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
2dac0 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
2dad0 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
2dae0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
2daf0 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
2db00 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
2db10 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
2db20 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
2db30 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
2db40 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2db50 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2db60 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
2db70 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
2db80 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
2db90 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
2dba0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
2dbb0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
2dbc0 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
2dbd0 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
2dbe0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
2dbf0 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
2dc00 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
2dc10 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
2dc20 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
2dc30 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
2dc40 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
2dc50 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
2dc60 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
2dc70 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
2dc80 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
2dc90 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
2dca0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
2dcb0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
2dcc0 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
2dcd0 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
2dce0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2dcf0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2dd00 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
2dd10 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
2dd20 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
2dd30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2dd40 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
2dd50 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
2dd60 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
2dd70 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2dd80 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
2dd90 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
2dda0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
2ddb0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
2ddc0 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
2ddd0 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
2dde0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2ddf0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
2de00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2de10 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
2de20 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
2de30 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2de40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2de50 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
2de60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2de70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2de80 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2de90 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
2dea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2deb0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68  t] belongs.  ^Th
2dec0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ded0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
2dee0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
2def0 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
2df00 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2df10 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
2df20 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
2df30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2df40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2df50 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
2df60 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
2df70 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
2df80 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
2df90 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2dfa0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2dfb0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
2dfc0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
2dfd0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2dfe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
2dff0 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
2e000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2e010 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2e020 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2e030 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
2e040 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
2e050 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
2e060 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
2e070 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
2e080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e090 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74   pDb.  ^If pStmt
2e0a0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
2e0b0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2e0c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e0d0 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
2e0e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e0f0 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
2e100 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
2e110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
2e120 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72  .  ^If no prepar
2e130 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2e140 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
2e150 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
2e160 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
2e170 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
2e180 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2e190 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
2e1a0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
2e1b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
2e1c0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
2e1d0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
2e1e0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
2e1f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
2e200 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
2e210 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
2e220 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69  pointer..*/.sqli
2e230 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
2e240 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
2e250 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
2e260 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2e270 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e280 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
2e290 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
2e2a0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
2e2b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2e2c0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
2e2d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2e2e0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2e2f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2e300 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2e310 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2e320 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
2e330 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
2e340 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2e350 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2e360 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
2e370 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
2e380 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2e390 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2e3a0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
2e3b0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
2e3c0 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
2e3d0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
2e3e0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
2e3f0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
2e400 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
2e410 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
2e420 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
2e430 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
2e440 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2e450 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2e460 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
2e470 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
2e480 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2e490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2e4a0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2e4b0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
2e4c0 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
2e4d0 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
2e4e0 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
2e4f0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
2e500 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
2e510 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
2e520 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
2e530 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
2e540 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
2e550 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2e560 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
2e570 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
2e580 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
2e590 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
2e5a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
2e5b0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
2e5c0 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
2e5d0 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
2e5e0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2e5f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2e600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e610 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2e620 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2e630 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
2e640 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
2e650 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
2e660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2e670 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2e680 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2e690 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2e6a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2e6b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
2e6c0 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
2e6d0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
2e6e0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
2e6f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2e700 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
2e710 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
2e720 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
2e730 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e740 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
2e750 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
2e760 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
2e770 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
2e780 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
2e790 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2e7a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2e7b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2e7c0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2e7d0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2e7e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2e7f0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2e800 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2e810 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2e820 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
2e830 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
2e840 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
2e850 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
2e860 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2e870 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2e880 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
2e890 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
2e8a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
2e8b0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
2e8c0 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
2e8d0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
2e8e0 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
2e8f0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
2e900 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
2e910 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
2e920 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
2e930 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
2e940 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
2e950 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
2e960 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
2e970 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
2e980 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
2e990 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
2e9a0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
2e9b0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2e9c0 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
2e9d0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
2e9e0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2e9f0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
2ea00 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
2ea10 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
2ea20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
2ea30 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
2ea40 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
2ea50 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
2ea60 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
2ea70 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
2ea80 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
2ea90 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
2eaa0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
2eab0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2eac0 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2ead0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
2eae0 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
2eaf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2eb00 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
2eb10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2eb20 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2eb30 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
2eb40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2eb50 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
2eb60 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
2eb70 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
2eb80 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
2eb90 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
2eba0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
2ebb0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
2ebc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2ebd0 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
2ebe0 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2ebf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ec00 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2ec10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2ec20 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2ec30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
2ec40 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2ec50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
2ec60 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
2ec70 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2ec80 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2ec90 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
2eca0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2ecb0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2ecc0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
2ecd0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
2ece0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
2ecf0 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
2ed00 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2ed10 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
2ed20 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
2ed30 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2ed40 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2ed50 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
2ed60 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
2ed70 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
2ed80 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2ed90 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
2eda0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2edb0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
2edc0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
2edd0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2ede0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2edf0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
2ee00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
2ee10 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
2ee20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2ee30 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
2ee40 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
2ee50 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
2ee60 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
2ee70 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
2ee80 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
2ee90 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
2eea0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
2eeb0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2eec0 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
2eed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
2eee0 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
2eef0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2ef00 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
2ef10 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
2ef20 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
2ef30 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
2ef40 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
2ef50 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
2ef60 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
2ef70 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
2ef80 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
2ef90 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
2efa0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
2efb0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
2efc0 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2efd0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2efe0 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
2eff0 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
2f000 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
2f010 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
2f020 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
2f030 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
2f040 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
2f050 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
2f060 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2f070 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2f080 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
2f090 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2f0a0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
2f0b0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
2f0c0 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
2f0d0 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
2f0e0 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
2f0f0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
2f100 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
2f110 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
2f120 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
2f130 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
2f140 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
2f150 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
2f160 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
2f170 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
2f180 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
2f190 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
2f1a0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
2f1b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2f1c0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
2f1d0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
2f1e0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2f1f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2f200 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
2f210 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
2f220 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2f230 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2f240 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2f250 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2f260 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2f270 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2f280 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2f290 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2f2a0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
2f2b0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
2f2c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
2f2d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2f2e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f2f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
2f300 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
2f310 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
2f320 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
2f330 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
2f340 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
2f350 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
2f360 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
2f370 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
2f380 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
2f390 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
2f3a0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
2f3b0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2f3c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2f3d0 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
2f3e0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2f3f0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
2f400 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
2f410 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
2f420 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
2f430 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
2f440 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
2f450 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2f460 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2f470 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2f480 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2f490 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2f4a0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2f4b0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2f4c0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2f4d0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2f4e0 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2f4f0 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
2f500 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
2f510 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
2f520 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
2f530 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
2f540 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
2f550 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
2f560 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
2f570 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
2f580 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
2f590 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
2f5a0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
2f5b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2f5c0 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
2f5d0 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
2f5e0 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
2f5f0 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
2f600 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2f610 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
2f620 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
2f630 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
2f640 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
2f650 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
2f660 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
2f670 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
2f680 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
2f690 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
2f6a0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
2f6b0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
2f6c0 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
2f6d0 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
2f6e0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2f6f0 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
2f700 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
2f710 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f720 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
2f730 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
2f740 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
2f750 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2f760 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
2f770 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2f780 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
2f790 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f7a0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
2f7b0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
2f7c0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
2f7d0 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
2f7e0 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
2f7f0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
2f800 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
2f810 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2f820 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
2f830 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
2f840 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
2f850 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
2f860 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2f870 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
2f880 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
2f890 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
2f8a0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
2f8b0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
2f8c0 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
2f8d0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2f8e0 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
2f8f0 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
2f900 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
2f910 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
2f920 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
2f930 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
2f940 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
2f950 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
2f960 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2f970 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
2f980 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
2f990 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
2f9a0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
2f9b0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
2f9c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
2f9d0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
2f9e0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2f9f0 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
2fa00 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
2fa10 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
2fa20 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2fa30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2fa40 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
2fa50 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
2fa60 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
2fa70 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
2fa80 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
2fa90 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
2faa0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
2fab0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
2fac0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
2fad0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2fae0 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
2faf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2fb00 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
2fb10 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
2fb20 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
2fb30 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
2fb40 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
2fb50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
2fb60 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
2fb70 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
2fb80 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
2fb90 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
2fba0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
2fbb0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
2fbc0 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
2fbd0 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  NT]..*/.int sqli
2fbe0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2fbf0 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
2fc00 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
2fc10 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
2fc20 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
2fc30 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
2fc40 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72  ap_limit() inter
2fc50 66 61 63 65 20 70 6c 61 63 65 73 20 61 20 22 73  face places a "s
2fc60 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e  oft" limit.** on
2fc70 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68   the amount of h
2fc80 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  eap memory that 
2fc90 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  may be allocated
2fca0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e   by SQLite..** ^
2fcb0 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61  If an internal a
2fcc0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71  llocation is req
2fcd0 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c  uested that woul
2fce0 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  d exceed the.** 
2fcf0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
2fd00 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2fd10 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69  e_memory()] is i
2fd20 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a  nvoked one or.**
2fd30 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66   more times to f
2fd40 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63  ree up some spac
2fd50 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c  e before the all
2fd60 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f  ocation is perfo
2fd70 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
2fd80 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
2fd90 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65 20   "soft" because 
2fda0 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  if [sqlite3_rele
2fdb0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a  ase_memory()].**
2fdc0 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66   cannot free suf
2fdd0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74  ficient memory t
2fde0 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69  o prevent the li
2fdf0 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65  mit from being e
2fe00 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20  xceeded,.** the 
2fe10 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61  memory is alloca
2fe20 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74  ted anyway and t
2fe30 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  he current opera
2fe40 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a  tion proceeds..*
2fe50 2a 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  *.** ^A negative
2fe60 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
2fe70 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
2fe80 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
2fe90 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
2fea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
2feb0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
2fec0 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
2fed0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
2fee0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
2fef0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2ff00 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
2ff10 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
2ff20 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  o..**.** ^(SQLit
2ff30 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65  e makes a best e
2ff40 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74  ffort to honor t
2ff50 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2ff60 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68  it..** But if th
2ff70 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2ff80 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f  t cannot be hono
2ff90 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77  red, execution w
2ffa0 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20  ill.** continue 
2ffb0 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72  without error or
2ffc0 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e   notification.)^
2ffd0 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
2ffe0 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61  e limit is.** ca
2fff0 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
30000 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
30010 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
30020 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
30030 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
30040 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
30050 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
30060 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
30070 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
30080 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
30090 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
300a0 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
300b0 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
300c0 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
300d0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
300e0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
300f0 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
30100 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
30110 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
30120 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
30130 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
30140 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
30150 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
30160 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
30170 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
30180 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
30190 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
301a0 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
301b0 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
301c0 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
301d0 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
301e0 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ds..*/.void sqli
301f0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
30200 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mit(int);../*.**
30210 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 72 61   CAPI3REF: Extra
30220 63 74 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75  ct Metadata Abou
30230 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20  t A Column Of A 
30240 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Table.**.** ^Thi
30250 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
30260 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74  s metadata about
30270 20 61 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75   a specific colu
30280 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66 69 63  mn of a specific
30290 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74 61 62  .** database tab
302a0 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20 75 73  le accessible us
302b0 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62 61 73  ing the [databas
302c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
302d0 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61  ndle.** passed a
302e0 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
302f0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
30300 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e  *.** ^The column
30310 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
30320 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68  y the second, th
30330 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
30340 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20  arameters to.** 
30350 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
30360 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
30370 65 74 65 72 20 69 73 20 65 69 74 68 65 72 20 74  eter is either t
30380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
30390 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e  atabase.** (i.e.
303a0 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c   "main", "temp",
303b0 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64 20   or an attached 
303c0 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69  database) contai
303d0 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66 69  ning the specifi
303e0 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e  ed.** table or N
303f0 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e  ULL. ^If it is N
30400 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
30410 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
30420 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
30430 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
30440 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
30450 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20  gorithm used by 
30460 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
30470 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76  ine to.** resolv
30480 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
30490 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
304a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
304b0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
304c0 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66  meters to this f
304d0 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20  unction are the 
304e0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
304f0 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  .** name of the 
30500 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20  desired column, 
30510 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65  respectively. Ne
30520 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70  ither of these p
30530 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79  arameters.** may
30540 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
30550 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74  ^Metadata is ret
30560 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
30570 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
30580 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
30590 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
305a0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
305b0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
305c0 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f  function. ^Any o
305d0 66 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74  f these argument
305e0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c  s may be.** NULL
305f0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
30600 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
30610 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
30620 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64  adata is omitted
30630 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b  ..**.** ^(<block
30640 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
30650 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
30660 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74  <tr><th> Paramet
30670 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62  er <th> Output<b
30680 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73  r>Type <th>  Des
30690 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  cription.**.** <
306a0 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e  tr><td> 5th <td>
306b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
306c0 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c  > Data type.** <
306d0 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e  tr><td> 6th <td>
306e0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64   const char* <td
306f0 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c  > Name of defaul
30700 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  t collation sequ
30710 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ence.** <tr><td>
30720 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20   7th <td> int   
30730 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20        <td> True 
30740 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20  if column has a 
30750 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
30760 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  int.** <tr><td> 
30770 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  8th <td> int    
30780 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
30790 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74  f column is part
307a0 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52 59 20   of the PRIMARY 
307b0 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  KEY.** <tr><td> 
307c0 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20  9th <td> int    
307d0 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69       <td> True i
307e0 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54  f column is [AUT
307f0 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c  OINCREMENT].** <
30800 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
30810 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
30820 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   ^The memory poi
30830 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 63  nted to by the c
30840 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72  haracter pointer
30850 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74  s returned for t
30860 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f  he.** declaratio
30870 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61  n type and colla
30880 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
30890 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69   valid only unti
308a0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61  l the next.** ca
308b0 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65  ll to any SQLite
308c0 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
308d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  *.** ^If the spe
308e0 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20  cified table is 
308f0 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c  actually a view,
30900 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
30910 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
30920 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
30930 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
30940 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
30950 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
30960 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
30970 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
30980 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
30990 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
309a0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
309b0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
309c0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
309d0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
309e0 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20  ed column. ^(If 
309f0 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65  there is no.** e
30a00 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
30a10 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ed [INTEGER PRIM
30a20 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c  ARY KEY] column,
30a30 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
30a40 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
30a50 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
30a60 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
30a70 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
30a80 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
30a90 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
30aa0 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
30ab0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
30ac0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
30ad0 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
30ae0 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
30af0 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
30b00 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
30b10 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
30b20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
30b30 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
30b40 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
30b50 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
30b60 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
30b70 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
30b80 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
30b90 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
30ba0 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
30bb0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
30bc0 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
30bd0 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
30be0 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
30bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
30c00 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
30c10 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
30c20 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  msg()).)^.**.** 
30c30 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c  ^This API is onl
30c40 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
30c50 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
30c60 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
30c70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
30c80 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
30c90 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
30ca0 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  or symbol define
30cb0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
30cc0 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d  3_table_column_m
30cd0 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74  etadata(.  sqlit
30ce0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
30cf0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63         /* Connec
30d00 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  tion handle */. 
30d10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
30d20 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20  Name,        /* 
30d30 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72  Database name or
30d40 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74   NULL */.  const
30d50 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d   char *zTableNam
30d60 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20  e,     /* Table 
30d70 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  name */.  const 
30d80 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d  char *zColumnNam
30d90 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20  e,    /* Column 
30da0 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63  name */.  char c
30db0 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70  onst **pzDataTyp
30dc0 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a  e,    /* OUTPUT:
30dd0 20 44 65 63 6c 61 72 65 64 20 64 61 74 61 20 74   Declared data t
30de0 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f  ype */.  char co
30df0 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c  nst **pzCollSeq,
30e00 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
30e10 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  Collation sequen
30e20 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74  ce name */.  int
30e30 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20   *pNotNull,     
30e40 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
30e50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20  UT: True if NOT 
30e60 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20  NULL constraint 
30e70 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20  exists */.  int 
30e80 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20  *pPrimaryKey,   
30e90 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
30ea0 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
30eb0 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a  n part of PK */.
30ec0 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20    int *pAutoinc 
30ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30ee0 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
30ef0 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d   column is auto-
30f00 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a  increment */.);.
30f10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30f20 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
30f30 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  on.**.** ^This i
30f40 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61  nterface loads a
30f50 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  n SQLite extensi
30f60 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20  on library from 
30f70 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a  the named file..
30f80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30f90 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
30fa0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
30fb0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
30fc0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65  n.** SQLite exte
30fd0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
30fe0 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
30ff0 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a  ile zFile..**.**
31000 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e   ^The entry poin
31010 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e  t is zProc..** ^
31020 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20  zProc may be 0, 
31030 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
31040 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e  e name of the en
31050 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66  try point.** def
31060 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65  aults to "sqlite
31070 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74  3_extension_init
31080 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  "..** ^The sqlit
31090 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
310a0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  n() interface re
310b0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
310c0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
310d0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  and [SQLITE_ERRO
310e0 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20  R] if something 
310f0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
31100 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
31110 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20  rs and pzErrMsg 
31120 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74  is not 0, then t
31130 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  he.** [sqlite3_l
31140 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
31150 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
31160 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66   attempt to.** f
31170 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69  ill *pzErrMsg wi
31180 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  th error message
31190 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20   text stored in 
311a0 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e  memory.** obtain
311b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
311c0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20  _malloc()]. The 
311d0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
311e0 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20  .** should free 
311f0 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63  this memory by c
31200 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
31210 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
31220 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
31230 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65  g must be enable
31240 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
31250 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
31260 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
31270 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68  or to calling th
31280 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72  is API,.** other
31290 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69  wise an error wi
312a0 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a  ll be returned..
312b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
312c0 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
312d0 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  on() SQL functio
312e0 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  n]..*/.int sqlit
312f0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
31300 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
31310 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
31320 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
31330 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
31340 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
31350 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
31360 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
31370 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
31380 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
31390 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
313a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
313b0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
313c0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
313d0 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
313e0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
313f0 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
31400 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
31410 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
31420 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
31430 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
31440 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
31450 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
31460 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70  ^So as not to op
31470 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65  en security hole
31480 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69  s in older appli
31490 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  cations that are
314a0 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74  .** unprepared t
314b0 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74 65  o deal with exte
314c0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61  nsion loading, a
314d0 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66  nd as a means of
314e0 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78   disabling.** ex
314f0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
31500 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
31510 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
31520 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  L, the following
31530 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69   API.** is provi
31540 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20  ded to turn the 
31550 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
31560 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61  tension()] mecha
31570 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e  nism on and off.
31580 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f  .**.** ^Extensio
31590 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66  n loading is off
315a0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65   by default. See
315b0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
315c0 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69  * ^Call the sqli
315d0 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
315e0 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74  extension() rout
315f0 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d  ine with onoff==
31600 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74  1.** to turn ext
31610 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f  ension loading o
31620 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69  n and call it wi
31630 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74  th onoff==0 to t
31640 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f  urn.** it back o
31650 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74  ff again..*/.int
31660 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
31670 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73  load_extension(s
31680 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20  qlite3 *db, int 
31690 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
316a0 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74  API3REF: Automat
316b0 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45  ically Load An E
316c0 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  xtensions.**.** 
316d0 5e 54 68 69 73 20 41 50 49 20 63 61 6e 20 62 65  ^This API can be
316e0 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67   invoked at prog
316f0 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f  ram startup in o
31700 72 64 65 72 20 74 6f 20 72 65 67 69 73 74 65 72  rder to register
31710 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
31720 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65  statically linke
31730 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61  d extensions tha
31740 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61  t will be availa
31750 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65  ble.** to all ne
31760 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
31770 65 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20  ections]..**.** 
31780 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  ^(This routine s
31790 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
317a0 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
317b0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
317c0 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61 74  in an array that
317d0 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f   is obtained fro
317e0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
317f0 63 28 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f  c()].  That memo
31800 72 79 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63  ry.** is dealloc
31810 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
31820 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
31830 6e 73 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  nsion()].)^.**.*
31840 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
31850 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78   registers an ex
31860 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
31870 69 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61  int that is.** a
31880 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
31890 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
318a0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
318b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20  nnection].** is 
318c0 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71  opened using [sq
318d0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
318e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
318f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
31900 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a  3_open_v2()]..**
31910 20 5e 44 75 70 6c 69 63 61 74 65 20 65 78 74 65   ^Duplicate exte
31920 6e 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63  nsions are detec
31930 74 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74  ted so calling t
31940 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d  his routine.** m
31950 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
31960 74 68 20 74 68 65 20 73 61 6d 65 20 65 78 74 65  th the same exte
31970 6e 73 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73  nsion is harmles
31980 73 2e 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63  s..** ^Automatic
31990 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c   extensions appl
319a0 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72  y across all thr
319b0 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  eads..*/.int sql
319c0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
319d0 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
319e0 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
319f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31a00 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
31a10 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
31a20 6e 67 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ng.**.** ^(This 
31a30 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
31a40 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
31a50 20 72 65 67 69 73 74 65 72 65 64 20 61 75 74 6f   registered auto
31a60 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69  matic.** extensi
31a70 6f 6e 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74  ons. It undoes t
31a80 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
31a90 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74   prior.** [sqlit
31aa0 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
31ab0 6e 28 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a  n()] calls.)^.**
31ac0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
31ad0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f  on disables auto
31ae0 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
31af0 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e   in all threads.
31b00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
31b10 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65  _reset_auto_exte
31b20 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a  nsion(void);../*
31b30 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
31b40 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
31b50 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
31b60 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
31b70 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
31b80 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
31b90 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
31ba0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
31bb0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
31bc0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
31bd0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
31be0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
31bf0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
31c00 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
31c10 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
31c20 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
31c30 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
31c40 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
31c50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
31c60 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
31c70 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
31c80 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
31c90 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
31ca0 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64   Structures used
31cb0 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
31cc0 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a  table interface.
31cd0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
31ce0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  t sqlite3_vtab s
31cf0 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70  qlite3_vtab;.typ
31d00 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
31d10 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
31d20 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
31d30 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  o;.typedef struc
31d40 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
31d50 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74  ursor sqlite3_vt
31d60 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64  ab_cursor;.typed
31d70 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
31d80 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33  3_module sqlite3
31d90 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20  _module;../*.** 
31da0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
31db0 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a  l Table Object.*
31dc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
31dd0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
31de0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31df0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  }.**.** This str
31e00 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
31e10 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
31e20 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
31e30 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
31e40 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
31e50 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
31e60 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
31e70 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
31e80 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
31e90 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
31ea0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
31eb0 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
31ec0 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
31ed0 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
31ee0 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
31ef0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
31f00 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
31f10 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
31f20 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
31f30 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
31f40 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
31f50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
31f60 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
31f70 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
31f80 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
31f90 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
31fa0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
31fb0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
31fc0 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
31fd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31fe0 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
31ff0 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
32000 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
32010 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
32020 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
32030 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
32040 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
32050 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
32060 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
32070 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
32080 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
32090 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
320a0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
320b0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
320c0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
320d0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
320e0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
320f0 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
32100 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
32110 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
32120 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
32130 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
32140 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
32150 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
32160 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
32170 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
32180 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
32190 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
321a0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
321b0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
321c0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
321d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
321e0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
321f0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
32200 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
32210 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
32220 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
32230 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
32240 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
32250 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
32260 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
32270 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
32280 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
32290 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
322a0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
322b0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
322c0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
322d0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
322e0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
322f0 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
32300 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
32310 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
32320 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
32330 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
32340 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
32350 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
32360 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
32370 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
32380 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32390 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
323a0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
323b0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
323c0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
323d0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
323e0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
323f0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
32400 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
32410 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
32420 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
32430 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
32440 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
32450 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
32460 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
32470 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
32480 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
32490 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
324a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
324b0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
324c0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
324d0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
324e0 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
324f0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
32500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32510 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
32520 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
32530 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
32540 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
32550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32560 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
32570 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  g);.  int (*xRen
32580 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
32590 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
325a0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
325b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
325c0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
325d0 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74  ndexing Informat
325e0 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ion.** KEYWORDS:
325f0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
32600 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nfo.**.** The sq
32610 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
32620 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
32630 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
32640 20 69 73 20 75 73 65 64 20 61 73 20 70 61 72 74   is used as part
32650 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
32660 75 61 6c 20 74 61 62 6c 65 5d 20 69 6e 74 65 72  ual table] inter
32670 66 61 63 65 20 74 6f 0a 2a 2a 20 70 61 73 73 20  face to.** pass 
32680 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
32690 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
326a0 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
326b0 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20  [xBestIndex].** 
326c0 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72  method of a [vir
326d0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
326e0 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  e].  The fields 
326f0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
32700 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
32710 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
32720 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
32730 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
32740 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
32750 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
32760 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
32770 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ds..**.** ^(The 
32780 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
32790 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52  ray records WHER
327a0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
327b0 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ints of the form
327c0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
327d0 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78  ote>column OP ex
327e0 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  pr</blockquote>.
327f0 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
32800 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
32810 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
32820 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69  .)^  ^(The parti
32830 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
32840 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61  s.** stored in a
32850 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20  Constraint[].op 
32860 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
32870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 44 45  .** [SQLITE_INDE
32880 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
32890 7c 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  | SQLITE_INDEX_C
328a0 4f 4e 53 54 52 41 49 4e 54 5f 20 76 61 6c 75 65  ONSTRAINT_ value
328b0 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 69  s].)^.** ^(The i
328c0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
328d0 6d 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a  mn is stored in.
328e0 2a 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ** aConstraint[]
328f0 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61  .iColumn.)^  ^(a
32900 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
32910 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
32920 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
32930 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
32940 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
32950 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
32960 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
32970 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
32980 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
32990 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  .)^.**.** ^The o
329a0 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74  ptimizer automat
329b0 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74  ically inverts t
329c0 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  erms of the form
329d0 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e   "expr OP column
329e0 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f  ".** and makes o
329f0 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74  ther simplificat
32a00 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52  ions to the WHER
32a10 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61  E clause in an a
32a20 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74  ttempt to.** get
32a30 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63   as many WHERE c
32a40 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f  lause terms into
32a50 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20   the form shown 
32a60 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c  above as possibl
32a70 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73  e..** ^The aCons
32a80 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f  traint[] array o
32a90 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52  nly reports WHER
32aa0 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74  E clause terms t
32ab0 68 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76  hat are.** relev
32ac0 61 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74 69  ant to the parti
32ad0 63 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61  cular virtual ta
32ae0 62 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65  ble being querie
32af0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d  d..**.** ^Inform
32b00 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
32b10 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
32b20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72  is stored in aOr
32b30 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63  derBy[]..** ^Eac
32b40 68 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72  h term of aOrder
32b50 42 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c  By records a col
32b60 75 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52  umn of the ORDER
32b70 20 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a   BY clause..**.*
32b80 2a 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65  * The [xBestInde
32b90 78 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66  x] method must f
32ba0 69 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ill aConstraintU
32bb0 73 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f  sage[] with info
32bc0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
32bd0 20 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73   what parameters
32be0 20 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c   to pass to xFil
32bf0 74 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e  ter.  ^If argvIn
32c00 64 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68  dex>0 then.** th
32c10 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
32c20 65 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70  e of the corresp
32c30 6f 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69  onding aConstrai
32c40 6e 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65  nt[] is evaluate
32c50 64 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73  d.** and becomes
32c60 20 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74   the argvIndex-t
32c70 68 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e  h entry in argv.
32c80 20 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69    ^(If aConstrai
32c90 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a  ntUsage[].omit.*
32ca0 2a 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20  * is true, then 
32cb0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  the constraint i
32cc0 73 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20  s assumed to be 
32cd0 66 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79  fully handled by
32ce0 20 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20   the.** virtual 
32cf0 74 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74  table and is not
32d00 20 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62   checked again b
32d10 79 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a  y SQLite.)^.**.*
32d20 2a 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e  * ^The idxNum an
32d30 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20  d idxPtr values 
32d40 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64  are recorded and
32d50 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
32d60 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65  .** [xFilter] me
32d70 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74  thod..** ^[sqlit
32d80 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73  e3_free()] is us
32d90 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
32da0 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  r if and only if
32db0 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64  .** needToFreeId
32dc0 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
32dd0 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79  .** ^The orderBy
32de0 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
32df0 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
32e00 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74  [xFilter]/[xNext
32e10 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a  ] will occur in.
32e20 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f  ** the correct o
32e30 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20  rder to satisfy 
32e40 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
32e50 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73  use so that no s
32e60 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69  eparate.** sorti
32e70 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69  ng step is requi
32e80 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
32e90 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
32ea0 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
32eb0 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
32ec0 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
32ed0 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
32ee0 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
32ef0 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
32f00 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
32f10 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
32f20 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
32f30 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
32f40 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
32f50 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
32f60 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
32f70 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a  tely log(N)..*/.
32f80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
32f90 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a  ndex_info {.  /*
32fa0 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74   Inputs */.  int
32fb0 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   nConstraint;   
32fc0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
32fd0 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
32fe0 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20  aConstraint */. 
32ff0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
33000 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
33010 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
33020 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
33030 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c    /* Column on l
33040 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
33050 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
33060 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
33070 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a  r op;         /*
33080 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72   Constraint oper
33090 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  ator */.     uns
330a0 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c  igned char usabl
330b0 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69  e;     /* True i
330c0 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  f this constrain
330d0 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20  t is usable */. 
330e0 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
330f0 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
33100 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
33110 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
33120 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
33130 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b   } *aConstraint;
33140 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
33150 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c  able of WHERE cl
33160 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
33170 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72   */.  int nOrder
33180 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
33190 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   /* Number of te
331a0 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52  rms in the ORDER
331b0 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
331c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
331d0 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20  ndex_orderby {. 
331e0 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
331f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
33200 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a   Column number *
33210 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
33220 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
33230 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
33240 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
33250 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65  C. */.  } *aOrde
33260 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
33270 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20     /* The ORDER 
33280 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f  BY clause */.  /
33290 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73  * Outputs */.  s
332a0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
332b0 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75  dex_constraint_u
332c0 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61  sage {.    int a
332d0 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20  rgvIndex;       
332e0 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f      /* if >0, co
332f0 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74  nstraint is part
33300 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c   of argv to xFil
33310 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67  ter */.    unsig
33320 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20  ned char omit;  
33330 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f      /* Do not co
33340 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68  de a test for th
33350 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  is constraint */
33360 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
33370 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64  tUsage;.  int id
33380 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20  xNum;           
33390 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75       /* Number u
333a0 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20  sed to identify 
333b0 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63  the index */.  c
333c0 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20  har *idxStr;    
333d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
333e0 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62  ing, possibly ob
333f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
33400 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20  te3_malloc */.  
33410 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64  int needToFreeId
33420 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72  xStr;      /* Fr
33430 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20  ee idxStr using 
33440 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
33450 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20  f true */.  int 
33460 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b  orderByConsumed;
33470 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69         /* True i
33480 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65  f output is alre
33490 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20  ady ordered */. 
334a0 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65   double estimate
334b0 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45  dCost;      /* E
334c0 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66  stimated cost of
334d0 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65   using this inde
334e0 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  x */.};../*.** C
334f0 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
33500 20 54 61 62 6c 65 20 43 6f 6e 73 74 72 61 69 6e   Table Constrain
33510 74 20 4f 70 65 72 61 74 6f 72 20 43 6f 64 65 73  t Operator Codes
33520 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
33530 72 6f 73 20 64 65 66 69 6e 65 64 20 74 68 65 20  ros defined the 
33540 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 66  allowed values f
33550 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  or the.** [sqlit
33560 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61  e3_index_info].a
33570 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20  Constraint[].op 
33580 66 69 65 6c 64 2e 20 20 45 61 63 68 20 76 61 6c  field.  Each val
33590 75 65 20 72 65 70 72 65 73 65 6e 74 73 0a 2a 2a  ue represents.**
335a0 20 61 6e 20 6f 70 65 72 61 74 6f 72 20 74 68 61   an operator tha
335b0 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 63  t is part of a c
335c0 6f 6e 73 74 72 61 69 6e 74 20 74 65 72 6d 20 69  onstraint term i
335d0 6e 20 74 68 65 20 77 48 45 52 45 20 63 6c 61 75  n the wHERE clau
335e0 73 65 20 6f 66 0a 2a 2a 20 61 20 71 75 65 72 79  se of.** a query
335f0 20 74 68 61 74 20 75 73 65 73 20 61 20 5b 76 69   that uses a [vi
33600 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
33610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33620 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
33630 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
33640 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
33650 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
33660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33670 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
33680 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
33690 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
336a0 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
336b0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
336c0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
336d0 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
336e0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
336f0 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
33700 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
33710 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
33720 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
33730 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a  plementation.**.
33740 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
33750 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72  es are used to r
33760 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76  egister a new [v
33770 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33780 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d  ule] name..** ^M
33790 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
337a0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
337b0 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e  efore.** creatin
337c0 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  g a new [virtual
337d0 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68   table] using th
337e0 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66  e module and bef
337f0 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70  ore using a.** p
33800 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74  reexisting [virt
33810 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74  ual table] for t
33820 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
33830 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d   ^The module nam
33840 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
33850 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
33860 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
33870 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
33880 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
33890 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  .  ^The name of 
338a0 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
338b0 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
338c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
338d0 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
338e0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
338f0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
33900 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33910 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
33920 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54  le module].   ^T
33930 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72  he fourth.** par
33940 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
33950 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61  itrary client da
33960 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
33970 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
33980 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78  h.** into the [x
33990 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
339a0 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
339b0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
339c0 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68  ble module.** wh
339d0 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c  en a new virtual
339e0 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69   table is be bei
339f0 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65  ng created or re
33a00 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a  initialized..**.
33a10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
33a20 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
33a30 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73  () interface has
33a40 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74   a fifth paramet
33a50 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
33a60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
33a70 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
33a80 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e   pClientData.  ^
33a90 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
33aa0 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
33ab0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
33ac0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
33ad0 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
33ae0 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
33af0 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
33b00 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
33b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
33b20 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
33b30 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
33b40 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
33b50 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
33b60 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
33b70 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69  destructor..*/.i
33b80 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
33b90 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
33ba0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33bb0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
33bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
33bd0 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
33be0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
33bf0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
33c00 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
33c10 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
33c20 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
33c30 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
33c40 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
33c50 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
33c60 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
33c70 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
33c80 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
33c90 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e  Connect */.);.in
33ca0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33cb0 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
33cc0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33cd0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
33ce0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
33cf0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
33d00 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
33d10 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
33d20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
33d30 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
33d40 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
33d50 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
33d60 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
33d70 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
33d80 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
33d90 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
33da0 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
33db0 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
33dc0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
33dd0 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
33de0 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
33df0 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
33e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
33e10 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
33e20 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  tance Object.** 
33e30 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
33e40 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
33e50 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
33e60 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
33e70 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
33e80 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74  subclass.** of t
33e90 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65  his object to de
33ea0 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
33eb0 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
33ec0 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
33ed0 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
33ee0 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
33ef0 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
33f00 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
33f10 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
33f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
33f30 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
33f40 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
33f50 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
33f60 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
33f70 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
33f80 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
33f90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
33fa0 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61  *.** ^Virtual ta
33fb0 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
33fc0 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
33fd0 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
33fe0 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
33ff0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
34000 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
34010 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
34020 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
34030 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
34040 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
34050 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
34060 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34070 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
34080 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
34090 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
340a0 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72  zErrMsg.  ^After
340b0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
340c0 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
340d0 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
340e0 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
340f0 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
34100 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
34110 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
34120 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
34130 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
34140 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
34150 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
34160 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
34170 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
34180 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
34190 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
341a0 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
341b0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
341c0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
341d0 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
341e0 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
341f0 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
34200 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
34210 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
34220 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
34230 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
34240 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
34250 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
34260 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
34270 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
34280 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
34290 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
342a0 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
342b0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
342c0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
342d0 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
342e0 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a  able cursor}.**.
342f0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
34300 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
34310 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
34320 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
34330 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
34340 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
34350 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
34360 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
34370 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
34380 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
34390 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
343a0 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
343b0 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
343c0 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
343d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
343e0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
343f0 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
34400 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
34410 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
34420 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
34430 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
34440 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
34450 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61  thod.  Cursors a
34460 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
34470 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
34480 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
34490 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
344a0 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
344b0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
344c0 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
344d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
344e0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
344f0 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
34500 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
34510 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
34520 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
34530 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
34540 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
34550 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
34560 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
34570 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
34580 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
34590 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
345a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
345b0 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
345c0 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
345d0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
345e0 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
345f0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
34600 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
34610 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
34620 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
34630 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
34640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34650 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
34660 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
34670 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  l Table.**.** ^T
34680 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
34690 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
346a0 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72  ods of a.** [vir
346b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
346c0 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74  e] call this int
346d0 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63  erface.** to dec
346e0 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
346f0 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
34700 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
34710 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
34720 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
34730 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
34740 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34750 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
34760 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
34770 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a  ar *zSQL);../*.*
34780 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72  * CAPI3REF: Over
34790 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20  load A Function 
347a0 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  For A Virtual Ta
347b0 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74  ble.**.** ^(Virt
347c0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
347d0 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
347e0 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
347f0 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
34800 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46  ** using the [xF
34810 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74  indFunction] met
34820 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74  hod of the [virt
34830 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
34840 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62  ].  .** But glob
34850 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
34860 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
34870 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
34880 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
34890 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  loaded.)^.**.** 
348a0 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
348b0 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
348c0 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
348d0 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
348e0 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
348f0 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
34900 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
34910 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
34920 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
34930 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
34940 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
34950 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
34960 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
34970 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
34980 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
34990 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
349a0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
349b0 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
349c0 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
349d0 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
349e0 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
349f0 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
34a00 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
34a10 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
34a20 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
34a30 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
34a40 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
34a50 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
34a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
34a70 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
34a80 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
34a90 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
34aa0 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
34ab0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
34ac0 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
34ad0 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
34ae0 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
34af0 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
34b00 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
34b10 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
34b20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
34b30 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
34b40 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
34b50 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
34b60 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
34b70 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
34b80 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
34b90 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
34ba0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
34bb0 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
34bc0 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
34bd0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
34be0 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
34bf0 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
34c00 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
34c10 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
34c20 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
34c30 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
34c40 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
34c50 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
34c60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
34c70 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
34c80 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f  en BLOB.** KEYWO
34c90 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
34ca0 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
34cb0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
34cc0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
34cd0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
34ce0 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
34cf0 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
34d00 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
34d10 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
34d20 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
34d30 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20  ed..** ^Objects 
34d40 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65  of this type are
34d50 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
34d60 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
34d70 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79  ].** and destroy
34d80 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
34d90 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
34da0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
34db0 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
34dc0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
34dd0 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
34de0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
34df0 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
34e00 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
34e10 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
34e20 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
34e30 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
34e40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34e50 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
34e60 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
34e70 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
34e80 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
34e90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
34ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
34eb0 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
34ec0 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
34ed0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
34ee0 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
34ef0 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
34f00 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
34f10 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
34f20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
34f30 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
34f40 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
34f50 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
34f60 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
34f70 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
34f80 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
34f90 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
34fa0 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
34fb0 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
34fc0 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
34fd0 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
34fe0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  /pre>)^.**.** ^I
34ff0 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
35000 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
35010 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
35020 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
35030 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
35040 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20   access. ^If it 
35050 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
35060 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
35070 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20  read access..** 
35080 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
35090 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
350a0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
350b0 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72  t of an index or
350c0 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79   primary .** key
350d0 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49   for writing. ^I
350e0 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  f [foreign key c
350f0 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20  onstraints] are 
35100 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a  enabled, it is .
35110 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
35120 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
35130 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
35140 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66   a [child key] f
35150 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a  or writing..**.*
35160 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
35170 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
35180 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
35190 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
351a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
351b0 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
351c0 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
351d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
351e0 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66  at.** appears af
351f0 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
35200 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  rd when the data
35210 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
35220 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
35230 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61  ..** ^For the ma
35240 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
35250 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
35260 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
35270 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  * ^For TEMP tabl
35280 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
35290 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
352a0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
352b0 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
352c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
352d0 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
352e0 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
352f0 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
35300 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
35310 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
35320 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
35330 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
35340 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
35350 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75  r.)^.** ^This fu
35360 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
35370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35380 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
35390 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
353a0 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
353b0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
353c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
353d0 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
353e0 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
353f0 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  ns. ^Note that t
35400 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
35410 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
35420 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
35430 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
35440 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
35450 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
35460 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
35470 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
35480 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
35490 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
354a0 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
354b0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77  .** ^(If the row
354c0 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
354d0 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
354e0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
354f0 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
35500 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
35510 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
35520 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
35530 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
35540 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
35550 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
35560 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
35570 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
35580 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
35590 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
355a0 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
355b0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
355c0 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a   is open on.)^.*
355d0 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  * ^Calls to [sql
355e0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
355f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
35600 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
35610 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
35620 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
35630 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
35640 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
35650 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67  ORT]..** ^(Chang
35660 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  es written into 
35670 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20  a BLOB prior to 
35680 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e  the BLOB expirin
35690 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c  g are not.** rol
356a0 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20  led back by the 
356b0 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
356c0 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68  e BLOB.  Such ch
356d0 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74  anges will event
356e0 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20  ually.** commit 
356f0 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  if the transacti
35700 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  on continues to 
35710 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a  completion.)^.**
35720 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71  .** ^Use the [sq
35730 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
35740 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
35750 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
35760 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
35770 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65  ened blob.  ^The
35780 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
35790 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
357a0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e  ed by this.** in
357b0 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  terface.  Use th
357c0 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
357d0 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
357e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
357f0 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54  * blob..**.** ^T
35800 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
35810 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64  _zeroblob()] and
35820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35830 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74  _zeroblob()] int
35840 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74  erfaces.** and t
35850 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72  he built-in [zer
35860 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74  oblob] SQL funct
35870 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c  ion can be used,
35880 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20   if desired,.** 
35890 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70  to create an emp
358a0 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20  ty, zero-filled 
358b0 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f  blob in which to
358c0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75   read or write u
358d0 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74  sing.** this int
358e0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f  erface..**.** To
358f0 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63   avoid a resourc
35900 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70  e leak, every op
35910 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
35920 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c   should eventual
35930 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65  ly.** be release
35940 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
35950 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35960 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
35970 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
35980 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
35990 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
359a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
359b0 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
359c0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
359d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
359e0 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
359f0 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
35a00 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
35a10 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73  * CAPI3REF: Clos
35a20 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 0a  e A BLOB Handle.
35a30 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61 6e  **.** ^Closes an
35a40 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
35a50 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  le]..**.** ^Clos
35a60 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c  ing a BLOB shall
35a70 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72 65   cause the curre
35a80 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  nt transaction t
35a90 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74  o commit.** if t
35aa0 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65  here are no othe
35ab0 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64  r BLOBs, no pend
35ac0 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74 61  ing prepared sta
35ad0 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65  tements, and the
35ae0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
35af0 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61  nection is in [a
35b00 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e  utocommit mode].
35b10 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69 74  .** ^If any writ
35b20 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f 20  es were made to 
35b30 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d  the BLOB, they m
35b40 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e 20  ight be held in 
35b50 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74  cache.** until t
35b60 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74 69  he close operati
35b70 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c 20  on if they will 
35b80 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f  fit..**.** ^(Clo
35b90 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f 66  sing the BLOB of
35ba0 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20 63  ten forces the c
35bb0 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74 6f  hanges.** out to
35bc0 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66 20   disk and so if 
35bd0 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20 6f  any I/O errors o
35be0 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c 20  ccur, they will 
35bf0 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a 20  likely occur.** 
35c00 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
35c10 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f   the BLOB is clo
35c20 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72 73  sed.  Any errors
35c30 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72 69   that occur duri
35c40 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61 72  ng.** closing ar
35c50 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61 20  e reported as a 
35c60 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
35c70 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  value.)^.**.** ^
35c80 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f  (The BLOB is clo
35c90 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61  sed unconditiona
35ca0 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68  lly.  Even if th
35cb0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
35cc0 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63  ns.** an error c
35cd0 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73  ode, the BLOB is
35ce0 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e   still closed.)^
35cf0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
35d00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
35d10 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72  h a null pointer
35d20 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64 20   (such as would 
35d30 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  be returned.** b
35d40 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c 20  y a failed call 
35d50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35d60 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20 68  _open()]) is a h
35d70 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
35d80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  /.int sqlite3_bl
35d90 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33  ob_close(sqlite3
35da0 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _blob *);../*.**
35db0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72   CAPI3REF: Retur
35dc0 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41 6e  n The Size Of An
35dd0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a   Open BLOB.**.**
35de0 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73 69   ^Returns the si
35df0 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74  ze in bytes of t
35e00 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62  he BLOB accessib
35e10 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73  le via the .** s
35e20 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e  uccessfully open
35e30 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35e40 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67   in its only arg
35e50 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a 20  ument.  ^The.** 
35e60 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62  incremental blob
35e70 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63 61   I/O routines ca
35e80 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f  n only read or o
35e90 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73 74  verwriting exist
35ea0 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74  ing.** blob cont
35eb0 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74  ent; they cannot
35ec0 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
35ed0 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   of a blob..**.*
35ee0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
35ef0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
35f00 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
35f10 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
35f20 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
35f30 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
35f40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
35f50 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
35f60 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
35f70 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
35f80 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
35f90 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
35fa0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
35fb0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
35fc0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
35fd0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
35fe0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
35ff0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
36000 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
36010 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lob_bytes(sqlite
36020 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
36030 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61 64  * CAPI3REF: Read
36040 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f   Data From A BLO
36050 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a  B Incrementally.
36060 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
36070 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ction is used to
36080 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d 20   read data from 
36090 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
360a0 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20  ndle] into a.** 
360b0 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20  caller-supplied 
360c0 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73 20  buffer. N bytes 
360d0 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69  of data are copi
360e0 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20 5a  ed into buffer Z
360f0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  .** from the ope
36100 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
36110 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
36120 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  et.)^.**.** ^If 
36130 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
36140 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79  s less than N by
36150 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
36160 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a   of the BLOB,.**
36170 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
36180 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
36190 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e  no data is read.
361a0 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66 73    ^If N or iOffs
361b0 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68  et is.** less th
361c0 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54 45  an zero, [SQLITE
361d0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
361e0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
361f0 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68 65  is read..** ^The
36200 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f   size of the blo
36210 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  b (and hence the
36220 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
36230 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
36240 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
36250 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
36260 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
36270 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
36280 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
36290 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20  to read from an 
362a0 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
362b0 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
362c0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
362d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
362e0 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  RT]..**.** ^(On 
362f0 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33  success, sqlite3
36300 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65 74  _blob_read() ret
36310 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
36320 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
36330 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
36340 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
36350 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
36360 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  urned.)^.**.** T
36370 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
36380 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
36390 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
363a0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
363b0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
363c0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
363d0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
363e0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
363f0 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
36400 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
36410 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
36420 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
36430 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
36440 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
36450 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
36460 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
36470 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
36480 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
36490 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
364a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
364b0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
364c0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73 71  te3_blob_read(sq
364d0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f  lite3_blob *, vo
364e0 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e  id *Z, int N, in
364f0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
36500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72 69  ** CAPI3REF: Wri
36510 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20 42  te Data Into A B
36520 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
36530 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  y.**.** ^This fu
36540 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
36550 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e 74  o write data int
36560 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  o an open [BLOB 
36570 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a  handle] from a.*
36580 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
36590 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79 74  d buffer. ^N byt
365a0 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
365b0 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20 62  opied from the b
365c0 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20  uffer Z.** into 
365d0 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
365e0 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
365f0 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a  t iOffset..**.**
36600 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68   ^If the [BLOB h
36610 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
36620 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
36630 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e  ent was not open
36640 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e  ed for.** writin
36650 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
36660 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
36670 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
36680 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68  was zero),.** th
36690 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
366a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
366b0 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ONLY]..**.** ^Th
366c0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
366d0 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  only modify the 
366e0 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20  contents of the 
366f0 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e  BLOB; it is.** n
36700 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69  ot possible to i
36710 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65  ncrease the size
36720 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67   of a BLOB using
36730 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e 49   this API..** ^I
36740 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
36750 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
36760 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
36770 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
36780 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
36790 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
367a0 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
367b0 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73 0a  tten.  ^If N is.
367c0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  ** less than zer
367d0 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  o [SQLITE_ERROR]
367e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
367f0 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74   no data is writ
36800 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65  ten..** The size
36810 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61 6e   of the BLOB (an
36820 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
36830 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
36840 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
36850 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
36860 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
36870 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
36880 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
36890 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77 72  An attempt to wr
368a0 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72 65  ite to an expire
368b0 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  d [BLOB handle] 
368c0 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a  fails with an.**
368d0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
368e0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20 20  SQLITE_ABORT].  
368f0 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20 42  ^Writes to the B
36900 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72 65  LOB that occurre
36910 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  d.** before the 
36920 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65 78  [BLOB handle] ex
36930 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72 6f  pired are not ro
36940 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
36950 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  .** expiration o
36960 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74 68  f the handle, th
36970 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
36980 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69 67  hose changes mig
36990 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  ht.** have been 
369a0 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
369b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
369c0 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42 4c  t expired the BL
369d0 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20  OB handle.** or 
369e0 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65 6e  by other indepen
369f0 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 2e  dent statements.
36a00 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
36a10 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
36a20 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72 6e  b_write() return
36a30 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20  s SQLITE_OK..** 
36a40 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b  Otherwise, an  [
36a50 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
36a60 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
36a70 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
36a80 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69  ned.)^.**.** Thi
36a90 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
36aa0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
36ab0 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
36ac0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
36ad0 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
36ae0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
36af0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
36b00 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
36b10 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
36b20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
36b30 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
36b40 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
36b50 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
36b60 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
36b70 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
36b80 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
36b90 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
36ba0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
36bb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36bc0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
36bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36be0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c 69  _blob_write(sqli
36bf0 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73  te3_blob *, cons
36c00 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20 6e  t void *z, int n
36c10 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
36c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36c30 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53 79   Virtual File Sy
36c40 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a  stem Objects.**.
36c50 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69 6c  ** A virtual fil
36c60 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69 73  esystem (VFS) is
36c70 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
36c80 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61 74  ] object.** that
36c90 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f 20   SQLite uses to 
36ca0 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74 68  interact.** with
36cb0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
36cc0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
36cd0 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20 62  .  Most SQLite b
36ce0 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68 20  uilds come with 
36cf0 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66 61  a.** single defa
36d00 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73 20  ult VFS that is 
36d10 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
36d20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65  the host compute
36d30 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20  r..** New VFSes 
36d40 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65  can be registere
36d50 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20 56  d and existing V
36d60 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72 65  FSes can be unre
36d70 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68 65  gistered..** The
36d80 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72   following inter
36d90 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
36da0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
36db0 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
36dc0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36dd0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36de0 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74 73   a VFS given its
36df0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73   name..** ^Names
36e00 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69 74   are case sensit
36e10 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61  ive..** ^Names a
36e20 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
36e30 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
36e40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20 69  ..** ^If there i
36e50 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55  s no match, a NU
36e60 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
36e70 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a  turned..** ^If z
36e80 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  VfsName is NULL 
36e90 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
36ea0 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65 64   VFS is returned
36eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46 53  ..**.** ^New VFS
36ec0 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  es are registere
36ed0 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f 76  d with sqlite3_v
36ee0 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a 2a  fs_register()..*
36ef0 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53 20  * ^Each new VFS 
36f00 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66 61  becomes the defa
36f10 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20 6d  ult VFS if the m
36f20 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73 20  akeDflt flag is 
36f30 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61 6d  set..** ^The sam
36f40 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65 67  e VFS can be reg
36f50 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
36f60 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20 69   times without i
36f70 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61  njury..** ^To ma
36f80 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 56  ke an existing V
36f90 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66 61  FS into the defa
36fa0 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74 65  ult VFS, registe
36fb0 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77 69  r it again.** wi
36fc0 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20  th the makeDflt 
36fd0 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74 77  flag set.  If tw
36fe0 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53 65  o different VFSe
36ff0 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73 61  s with the.** sa
37000 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67 69  me name are regi
37010 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68 61  stered, the beha
37020 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
37030 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53 20  d.  If a.** VFS 
37040 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
37050 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20 69  th a name that i
37060 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
37070 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74 68  ty string,.** th
37080 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
37090 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
370a0 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72 20  .** ^Unregister 
370b0 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20 73  a VFS with the s
370c0 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
370d0 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61 63  ister() interfac
370e0 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 64  e..** ^(If the d
370f0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e  efault VFS is un
37100 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74  registered, anot
37110 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65  her VFS is chose
37120 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61  n as.** the defa
37130 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65  ult.  The choice
37140 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53   for the new VFS
37150 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29 5e   is arbitrary.)^
37160 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73 20  .*/.sqlite3_vfs 
37170 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  *sqlite3_vfs_fin
37180 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56  d(const char *zV
37190 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71 6c  fsName);.int sql
371a0 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
371b0 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  r(sqlite3_vfs*, 
371c0 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a 69  int makeDflt);.i
371d0 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  nt sqlite3_vfs_u
371e0 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65  nregister(sqlite
371f0 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  3_vfs*);../*.** 
37200 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 65  CAPI3REF: Mutexe
37210 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  s.**.** The SQLi
37220 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
37230 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  se routines for 
37240 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68 72  thread.** synchr
37250 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75 67  onization. Thoug
37260 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65 6e  h they are inten
37270 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ded for internal
37280 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
37290 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69 6e  e, code that lin
372a0 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69 74  ks against SQLit
372b0 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74 65  e is.** permitte
372c0 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66 20  d to use any of 
372d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
372e0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
372f0 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f 6e   source code con
37300 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20 69  tains multiple i
37310 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
37320 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65 78  * of these mutex
37330 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20 61   routines.  An a
37340 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c 65  ppropriate imple
37350 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
37360 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61 74  selected automat
37370 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69 6c  ically at compil
37380 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20 66  e-time.  ^(The f
37390 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c  ollowing.** impl
373a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20  ementations are 
373b0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
373c0 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a 2a   SQLite core:.**
373d0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
373e0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
373f0 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  OS2.** <li>   SQ
37400 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
37410 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  AD.** <li>   SQL
37420 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a 2a  ITE_MUTEX_W32.**
37430 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
37440 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75  UTEX_NOOP.** </u
37450 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
37460 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f  SQLITE_MUTEX_NOO
37470 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  P implementation
37480 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75   is a set of rou
37490 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  tines.** that do
374a0 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69  es no real locki
374b0 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70  ng and is approp
374c0 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e  riate for use in
374d0 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72  .** a single-thr
374e0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
374f0 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  n.  ^The SQLITE_
37500 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51  MUTEX_OS2,.** SQ
37510 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45  LITE_MUTEX_PTHRE
37520 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AD, and SQLITE_M
37530 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65  UTEX_W32 impleme
37540 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
37550 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
37560 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69  use on OS/2, Uni
37570 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a  x, and Windows..
37580 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
37590 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
375a0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d 55  th the SQLITE_MU
375b0 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70 72  TEX_APPDEF prepr
375c0 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f  ocessor.** macro
375d0 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20 22   defined (with "
375e0 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  -DSQLITE_MUTEX_A
375f0 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e 20  PPDEF=1"), then 
37600 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  no mutex.** impl
37610 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69 6e  ementation is in
37620 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65 20  cluded with the 
37630 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69 73  library. In this
37640 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70 70   case the.** app
37650 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
37660 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d 75  pply a custom mu
37670 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
37680 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  on using the.** 
37690 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
376a0 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66 20  UTEX] option of 
376b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  the sqlite3_conf
376c0 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ig() function.**
376d0 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20   before calling 
376e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
376f0 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68 65  ze() or any othe
37700 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  r public sqlite3
37710 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68  _.** function th
37720 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  at calls sqlite3
37730 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29 5e  _initialize().)^
37740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37750 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
37760 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63 61  ) routine alloca
37770 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75 74  tes a new.** mut
37780 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ex and returns a
37790 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20   pointer to it. 
377a0 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ^If it returns N
377b0 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61 6e  ULL.** that mean
377c0 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20 63  s that a mutex c
377d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c 6f  ould not be allo
377e0 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65 0a  cated.  ^SQLite.
377f0 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20 69  ** will unwind i
37800 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65 74  ts stack and ret
37810 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  urn an error.  ^
37820 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  (The argument.**
37830 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
37840 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65  x_alloc() is one
37850 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
37860 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a  r constants:.**.
37870 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
37880 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
37890 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ST.** <li>  SQLI
378a0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
378b0 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
378c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
378d0 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20  MASTER.** <li>  
378e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
378f0 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20  TIC_MEM.** <li> 
37900 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
37910 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69  ATIC_MEM2.** <li
37920 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
37930 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c  STATIC_PRNG.** <
37940 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
37950 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20  X_STATIC_LRU.** 
37960 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
37970 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a  EX_STATIC_LRU2.*
37980 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
37990 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20 63  ^The first two c
379a0 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54 45  onstants (SQLITE
379b0 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20  _MUTEX_FAST and 
379c0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
379d0 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73 65  URSIVE).** cause
379e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
379f0 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74 65  lloc() to create
37a00 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78 2e  .** a new mutex.
37a10 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65 78    ^The new mutex
37a20 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77 68   is recursive wh
37a30 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
37a40 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73 20  RECURSIVE.** is 
37a50 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65 63  used but not nec
37a60 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65 6e  essarily so when
37a70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
37a80 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20 54  ST is used..** T
37a90 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  he mutex impleme
37aa0 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
37ab0 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20   need to make a 
37ac0 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
37ad0 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55  etween SQLITE_MU
37ae0 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e  TEX_RECURSIVE an
37af0 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  d SQLITE_MUTEX_F
37b00 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a  AST if it does.*
37b10 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20  * not want to.  
37b20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c  ^SQLite will onl
37b30 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63 75  y request a recu
37b40 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a 2a  rsive mutex in.*
37b50 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69 74  * cases where it
37b60 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f 6e   really needs on
37b70 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65 72  e.  ^If a faster
37b80 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20 6d   non-recursive m
37b90 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
37ba0 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  tation is availa
37bb0 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74 20  ble on the host 
37bc0 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d 75  platform, the mu
37bd0 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  tex subsystem.**
37be0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73 75   might return su
37bf0 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72 65  ch a mutex in re
37c00 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54 45  sponse to SQLITE
37c10 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a  _MUTEX_FAST..**.
37c20 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61 6c  ** ^The other al
37c30 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72 73  lowed parameters
37c40 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
37c50 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74 68  x_alloc() (anyth
37c60 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68 61  ing other.** tha
37c70 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
37c80 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  AST and SQLITE_M
37c90 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20  UTEX_RECURSIVE) 
37ca0 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20 61  each return.** a
37cb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
37cc0 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e 67  atic preexisting
37cd0 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73 74   mutex.  ^Six st
37ce0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
37cf0 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20  .** used by the 
37d00 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
37d10 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75  of SQLite.  Futu
37d20 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
37d30 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64  QLite.** may add
37d40 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
37d50 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61  ic mutexes.  Sta
37d60 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20  tic mutexes are 
37d70 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
37d80 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  use by SQLite on
37d90 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ly.  Application
37da0 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
37db0 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  e mutexes should
37dc0 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65  .** use only the
37dd0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
37de0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
37df0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f  ITE_MUTEX_FAST o
37e00 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  r.** SQLITE_MUTE
37e10 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a  X_RECURSIVE..**.
37e20 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69 66  ** ^Note that if
37e30 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
37e40 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
37e50 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
37e60 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
37e70 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
37e80 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
37e90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
37ea0 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
37eb0 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
37ec0 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
37ed0 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20 74  all.  ^But for t
37ee0 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74  he static.** mut
37ef0 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
37f00 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
37f10 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
37f20 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
37f30 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
37f40 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
37f50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37f60 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
37f70 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
37f80 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
37f90 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
37fa0 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63 61  .  ^SQLite is ca
37fb0 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63  reful to dealloc
37fc0 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e  ate every.** dyn
37fd0 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20  amic mutex that 
37fe0 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20 54  it allocates.  T
37ff0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
38000 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69  es must not be i
38010 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68  n.** use when th
38020 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  ey are deallocat
38030 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67 20  ed.  Attempting 
38040 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20  to deallocate a 
38050 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20  static.** mutex 
38060 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
38070 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 20  ined behavior.  
38080 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65  ^SQLite never de
38090 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73  allocates.** a s
380a0 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a  tatic mutex..**.
380b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
380c0 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61 6e  mutex_enter() an
380d0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
380e0 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20 61  try() routines a
380f0 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e 74  ttempt.** to ent
38100 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49 66  er a mutex.  ^If
38110 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
38120 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68 69  is already withi
38130 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a 20  n the mutex,.** 
38140 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
38150 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63 6b  ter() will block
38160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
38170 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72 65  ex_try() will re
38180 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 42  turn.** SQLITE_B
38190 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  USY.  ^The sqlit
381a0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 69  e3_mutex_try() i
381b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
381c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20   [SQLITE_OK].** 
381d0 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c 20  upon successful 
381e0 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78 65  entry.  ^(Mutexe
381f0 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
38200 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
38210 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62 65  RECURSIVE can be
38220 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70 6c   entered multipl
38230 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20 73  e times by the s
38240 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  ame thread..** I
38250 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68 65  n such cases the
38260 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74 20  ,.** mutex must 
38270 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71 75  be exited an equ
38280 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  al number of tim
38290 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68 65  es before anothe
382a0 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e 20  r thread.** can 
382b0 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20 74  enter.)^  ^(If t
382c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74  he same thread t
382d0 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e  ries to enter an
382e0 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20  y other.** kind 
382f0 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68  of mutex more th
38300 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68  an once, the beh
38310 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
38320 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ed..** SQLite wi
38330 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
38340 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
38350 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
38360 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a   of mutexes.)^.*
38370 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73 74  *.** ^(Some syst
38380 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ems (for example
38390 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64 6f  , Windows 95) do
383a0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68 65   not support the
383b0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d   operation.** im
383c0 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71 6c  plemented by sql
383d0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
383e0 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73 74  .  On those syst
383f0 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  ems, sqlite3_mut
38400 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c 6c  ex_try().** will
38410 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 53   always return S
38420 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68 65  QLITE_BUSY.  The
38430 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c   SQLite core onl
38440 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20 73  y ever uses.** s
38450 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
38460 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a  () as an optimiz
38470 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69 73  ation so this is
38480 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68 61   acceptable beha
38490 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  vior.)^.**.** ^T
384a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
384b0 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e 65  _leave() routine
384c0 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20 74   exits a mutex t
384d0 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  hat was.** previ
384e0 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ously entered by
384f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
38500 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76 69  .   ^(The behavi
38510 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
38520 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78 20  ed if the mutex 
38530 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
38540 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 0a   entered by the.
38550 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  ** calling threa
38560 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72 72  d or is not curr
38570 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64 2e  ently allocated.
38580 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
38590 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65 72   never do either
385a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
385b0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
385c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
385d0 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74  r(), sqlite3_mut
385e0 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20  ex_try(), or.** 
385f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
38600 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  ave() is a NULL 
38610 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c  pointer, then al
38620 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  l three routines
38630 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e 6f  .** behave as no
38640 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  -ops..**.** See 
38650 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d  also: [sqlite3_m
38660 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64  utex_held()] and
38670 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
38680 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73  notheld()]..*/.s
38690 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71  qlite3_mutex *sq
386a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
386b0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  c(int);.void sql
386c0 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
386d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
386e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
386f0 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74 65  tex_enter(sqlite
38700 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
38710 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
38720 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
38730 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
38740 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69 74  utex_leave(sqlit
38750 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a  e3_mutex*);../*.
38760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
38770 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  ex Methods Objec
38780 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
38790 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
387a0 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68  cture defines th
387b0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74  e low-level rout
387c0 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ines.** used to 
387d0 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65  allocate and use
387e0 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20   mutexes..**.** 
387f0 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66  Usually, the def
38800 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65  ault mutex imple
38810 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69  mentations provi
38820 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72  ded by SQLite ar
38830 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c  e.** sufficient,
38840 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65   however the use
38850 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e  r has the option
38860 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67   of substituting
38870 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70   a custom.** imp
38880 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  lementation for 
38890 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c  specialized depl
388a0 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65  oyments or syste
388b0 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c  ms for which SQL
388c0 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
388d0 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62  provide a suitab
388e0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
388f0 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c  n. In this case,
38900 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65   the user.** cre
38910 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74  ates and populat
38920 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  es an instance o
38930 66 20 74 68 69 73 2